You can use the SysCert model pattern to generate, validate, and log in with SAML2 tokens when you need token-based authentication in a MDriven Turnkey application.

Add SAML2 support to your model

SAML2 is an XML-based token format. Add the SysCert model pattern before you generate or validate SAML2 tokens.

1. Import the SysCert.ecomdl merge file into your model.
2. Use the imported SysCert pattern to create certificates with your own common name (CN), import the public-key part of an external certificate, generate SAML2 tokens, and validate SAML2 tokens.
3. Deploy the updated model to the Turnkey application that will issue or validate the token.

The SysCert pattern also supports JWT. For JWT-specific authentication behavior, see Documentation:Authenticate with a jwt.

Choose the certificate role

Use a certificate according to whether the application issues tokens or validates tokens.

Application role	Certificate material	What you can do
Token issuer	A complete certificate that includes the private key	Generate SAML2 tokens.
Token consumer	The public-key part of the issuer's certificate	Validate SAML2 tokens issued by the certificate owner.

For example, one MDriven system can issue a SAML2 token with its complete certificate. A second MDriven system can import the first system's public certificate and validate the token. The second system cannot generate tokens for that certificate because it does not have the private key.

Generate and transport a SAML2 token

1. Generate a SAML2 token through the SysCert pattern.
2. If the token must be sent as a URL parameter, use the pattern's Base64 form. A raw XML token and ordinary Base64 can contain characters that are unsuitable for a URL parameter.
3. Send the token to the SAML2 login flow together with the key identity of the certificate that issued it.

Unlike JWT, SAML2 tokens do not contain a key identity for certificate rotation. The SAML2 login flow can therefore use the key identity provided together with the token so that the receiving application can select the certificate used for validation.

Log in with a SAML2 token

Use the Turnkey controller named TryLoginWithSaml2 to attempt a SAML2-token login.

1. Generate the SAML2 token with the issuing certificate.
2. Provide the token in its web-safe Base64 form when it is sent as a URL parameter.
3. Provide the issuing certificate's key identity with the token.
4. Call TryLoginWithSaml2.
5. Handle a rejected login by redirecting the user to an appropriate login or error flow.

Validate tokens from an external issuer

When another system issues the SAML2 token, import that issuer's public certificate into SysCert. The public certificate lets your application verify that a presented token was issued by the trusted certificate owner. It does not let your application issue tokens as that external issuer.

Keep the certificate key identity aligned between the issuing system and the login request. This is especially important when you maintain more than one certificate for key rotation.

See also

• Documentation:Authenticate with a jwt
• Documentation:SingleSignOn
• Documentation:OpenID config
• Documentation:Connecting javascript SinglePageApplications to Turnkey (SPA)
• Watch the SysCert JWT and SAML2 walkthrough