You can use SAML2 tokens with a Turnkey application when you need to generate or validate XML-based authentication tokens through the SysCert model pattern.
What MDriven supports
SAML2 is an XML-based token format. In MDriven, the SysCert model pattern can generate and validate both SAML2 and JWT tokens. SAML2 is an older token format than JWT.
Use SAML2 when the system that issues or consumes the login token requires that format. For example, one MDriven system can issue a token with a certificate that contains a private key, while another system imports the issuer's public certificate and validates the received token.
Prepare the model
- Use the SysCert model pattern to create your own certificate or import the public part of an external certificate.
- Generate a SAML2 token when your application is the token issuer.
- Validate a received SAML2 token when your application trusts the issuer's certificate.
A certificate that includes its private key can issue tokens. A certificate that contains only the public key can validate tokens issued by the certificate owner, but cannot generate tokens.
Generate and send a SAML2 token
A SAML2 token is XML-based. When you need to pass the token as a URL parameter, generate the SAML2 token in Base64 form. URL parameters can be affected by characters such as + and /, so use the web-safe Base64 representation shown by the SysCert pattern rather than sending raw XML.
To log in with a SAML2 token, provide both:
- The SAML2 token.
- The key identity for the certificate that issued the token.
You must send the key identity together with the token so that Turnkey can select the certificate used for validation.
Import an issuer certificate
When an external identity system issues the token, import that issuer's public certificate into SysCert. The public certificate lets MDriven verify that a received token was issued by the expected party.
For example, an external issuer can publish a certificate together with its key identity. Import the certificate text into SysCert and assign the corresponding key identity. Do not expect an imported public-only certificate to generate a token: it does not contain the private key.
Certificate roles
| Certificate content | Use in the SAML2 flow |
|---|---|
| Private and public key | Generate SAML2 tokens and validate tokens. |
| Public key only | Validate tokens from the certificate owner; cannot generate tokens. |
Troubleshooting
Token cannot be validated
Check that the key identity sent with the SAML2 token identifies a certificate stored in SysCert. A token issued with one key identity will not validate if that key identity does not exist in persistent storage.
Token generation fails
Check whether the selected certificate has a private key. An imported public certificate can validate tokens but cannot issue them.
Login is rejected
Check that the SAML2 token and its key identity are both included in the login request. Handle failed login with an appropriate redirect or error view in your application.
Token does not survive URL transport
Do not send raw XML as a URL parameter. Generate the SAML2 token in the web-safe Base64 form used for URL transport.
Supplemental walkthrough
For a demonstration of creating certificates, generating SAML2 tokens, importing public certificates, and logging in with a token, watch the certificate, JWT, and SAML2 walkthrough.