10Duke Enterprise release 3 documentation is no longer being updated

Implement authentication with SAML

10Duke Enterprise supports SAML 2.0 Web Browser SSO Profile (SP-initiated) for user authentication. You can connect your client application using SAML when you need to provide single sign-on (SSO) for your users.

If your application needs to consume licenses or access 10Duke APIs, connect it using OIDC instead.

Implementing SAML for your client application from scratch is difficult. There are plenty of libraries available, and we recommend that you find a library suitable for your client application to handle SAML for you.

Before you start

Define a SAML connection for your client application in 10Duke SysAdmin.

  • This includes defining the SAML entity ID of your client application (SP), and the endpoint URL of your client application for receiving the response (SP assertion consumer service).

  • Add the response attributes using attribute names that your client application (SP) expects to receive from the IdP.

Step 1: Initiate authentication flow

From the client application (SP), send the user agent (browser) to the 10Duke Authentication API’s authentication endpoint.

An example URL where the browser is sent (line breaks added for display purposes):

<BASE_URL>/user/saml20/signon
   ?SAMLRequest=jVNNb...
   &RelayState=TestRelayState
   &SigAlg=http%3A%2F%2Fwww.w3.org%2F2000%2F09%2Fxmldsig%23rsa-sha1
   &Signature=pXb8z...

In the request query parameters, in SAMLRequest provide an encoded SAML authentication request (AuthnRequest) and in RelayState provide any value that you want to be sent back to your client application when authentication has been completed and 10Duke Enterprise sends a response back to your client application. In SigAlg and Signature, specify a cryptographic signature for the request.

Optional parameters:

  • If the user is not logged in yet, by default the login page is opened for them. With flow=register, you can request to open the registration page instead.

  • Provide the user’s email address in login_hint, which enables 10Duke Enterprise to automatically populate the email address field so the user doesn’t have to fill it in again.

When the end user has completed the login in the browser and been successfully authenticated, the browser is sent back to the client application’s (SP’s) callback URI (assertion consumer service).

Step 2: Handle SAML response

Handle the response sent back to the client application to read the SAML authentication response.

An example response (line breaks added for display purposes):

POST /my-client-acs
   Content-Type: application/x-www-form-urlencoded

   SAMLResponse=PHNhb...
   &RelayState=TestRelayState

From the SAMLResponse parameter, your client application can now read the SAML authentication response containing the details of the authenticated user.

Next steps

After successfully connecting your client application to 10Duke Enterprise, the client application is now integrated to an SSO environment.

Your end users can authenticate with 10Duke Enterprise, and new authentication features can be added without affecting your client application.

For example, customer federation or multi-factor authentication (MFA) can be set up: