How-tos

Setup Keycloak for Authentication

Instructions on how to enable users to authenticate with Keycloak as authentication provider. Learn how to connect and configure a user pool from Keycloak to the Cloudentity platform in accordance with the Bring Your Own Identity (BYOID) principle.

About Keycloak as an IDP

Keycloak is supported by Cloudentity via the generic SAML connector and generic OIDC connector in Cloudentity. This article shows how to connect Keycloak using the SAML Generic Connector

Keycloak and OIDC

Keycloak applications can also use the OIDC protocol, you can use the OIDC IDP to bind Keycloak apps via OIDC.

Prerequisites

  • To configure the connector, you need to retrieve the metadata from your SAML IDP applicaiton. This can be obtained by clicking on the metadata from the targeted realm setting in Keycloak.

  • A SAML Identity Provider in Keycloak with the following fields populated:

    Parameter Description
    Service Provider Entity ID URL of the realm in Keycloak, for example https://localhost:8443/auth/realms/demo.
    Single Sign-on Service URL SAML SSO URL of the realm in Keycloak, for example https://localhost:8443/auth/realms/demo/protocol/saml
    NameID Policy Format select Unspecified
  • Obtain the IdP certificate from your Keycloak realm

    • Inside the SAML metadata in your realm, copy the ds:X509Certificate value into a text file, prepend it with -----BEGIN CERTIFICATE----- and append -----END CERTIFICATE----- at the end, save the file and keep it open.
  • Keep Keycloak admin console open

Connect Keycloak IDP

Basic configuration

  1. In your workspace, go to Identity Data > Identity Providers > Create Identity.

  2. Select the SAML template and click Next.

  3. Add the Single Sign-on Service URL value from Keycloak in Sign in URL.

  4. Copy the X509 certificate file content into IDP certificate.

  5. Select unspecified in Name ID format.

  6. Optionally, enable Authentication context caching.

    Tip

    You can enable the authentication context caching if you want Cloudentity to store the user’s authentication data. If you do, specify the cache Time To Live as well. Learn more by reading Stateful authorization with Cloudentity.

  7. Optional: enable Identity Provider (IdP) Discovery and provide Email domains.

  8. Expand Advanced Settings and select Password-based authentication in Authentication Method Reference. Then save the changes.

  9. Select Save.

    Result

    Your new SAML identity provider is created and listed in the Consumer Identity Providers view.

    Entity issuer and Redirect URL (or Assertion Consumer Service (ACS)) are generated in Cloudentity. Use these values to finish the configuration on the SAML application side.

  10. Back in Keycloak, create a SAML client application.

  11. Put in Entity issuer from your workspace Keycloak IdP into Client ID.

  12. Select SAML in Client Protocol.

  13. Give a name in Name.

  14. These options need to be enabled: Enabled, Include AuthnStatement, Sign Documents, Sign Assertions. For testing purposes, do not enable Client Signature Required.

  15. Select username in Name ID Format.

  16. Put the workspace Keycloak IdP Redirect URL into Valid Redirect URIs and Master SAML Processing URL.

  17. Save the changes.

    Result

    Your new IDP connection is created configured. Users can now authenticate via the SAML-compliant IDP.

Add SAML IDP attributes

Make sure to add attributes sent by your SAML IDP to the IDP connector so that they can be recognized and mapped to the authentication context.

Consider the example below. All attributes within <saml2:AttributeStatement> can be extracted and mapped to the authentication context.

<?xml version="1.0" encoding="UTF-8"?>
<saml2:Assertion ID="id12606633554344727301514261" IssueInstant="2022-01-12T17:04:07.362Z" Version="2.0"
    xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
    <saml2:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">http://www.example.com/exk3ip7ehfTC30ReG5d7</saml2:Issuer>
    <saml2:Subject>
        <saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">example@mail.com</saml2:NameID>
        <saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
            <saml2:SubjectConfirmationData NotOnOrAfter="2022-01-12T17:09:07.362Z" Recipient="https://cloudentity-gkossobudzki.us.authz.stage.cloudentity.io/cloudentity-gkossobudzki/demo/login"/>
        </saml2:SubjectConfirmation>
    </saml2:Subject>
    <saml2:Conditions NotBefore="2022-01-12T16:59:07.362Z" NotOnOrAfter="2022-01-12T17:09:07.362Z">
        <saml2:AudienceRestriction>
            <saml2:Audience>c7bhamiqs3kro24r4peg</saml2:Audience>
        </saml2:AudienceRestriction>
    </saml2:Conditions>
    <saml2:AuthnStatement AuthnInstant="2022-01-12T17:04:07.362Z" SessionIndex="id1642007047361.940296625">
        <saml2:AuthnContext>
            <saml2:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</saml2:AuthnContextClassRef>
        </saml2:AuthnContext>
    </saml2:AuthnStatement>
    <saml2:AttributeStatement>
        <saml2:Attribute Name="employeeId" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
            <saml2:AttributeValue
                xmlns:xs="http://www.example.com/2001/XMLSchema"
                xmlns:xsi="http://www.example.com/2001/XMLSchema-instance" xsi:type="xs:string">JoeDoe123
            </saml2:AttributeValue>
        </saml2:Attribute>
        <saml2:Attribute Name="mail" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
            <saml2:AttributeValue
                xmlns:xs="http://www.example.com/2001/XMLSchema"
                xmlns:xsi="http://www.example.com/2001/XMLSchema-instance" xsi:type="xs:string">test@example.com
            </saml2:AttributeValue>
        </saml2:Attribute>
        <saml2:Attribute Name="https://example.com/groups" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
            <saml2:AttributeValue
                xmlns:xs="http://www.example.com/2001/XMLSchema"
                xmlns:xsi="http://www.example.com/2001/XMLSchema-instance" xsi:type="xs:string">administrators
            </saml2:AttributeValue>
            <saml2:AttributeValue
                xmlns:xs="http://www.example.com/2001/XMLSchema"
                xmlns:xsi="http://www.example.com/2001/XMLSchema-instance" xsi:type="xs:string">super_users
            </saml2:AttributeValue>
        </saml2:Attribute>
    </saml2:AttributeStatement>
</saml2:Assertion>
  1. Go to Identity Data > Identity Providers and select an IDP from the list.

  2. Open the Attributes page. A standard list of attributes returned by this IDP appears.

  3. Select Add attribute.

  4. Fill in the attribute form.

    Source Description
    SAML assertion attribute name Attribute received within the SAML assertion sent by the IDP, for example employeeId, mail or groups from the above sample.
    Display name Name representing this attribute in Cloudentity
    Data type Data type of the incoming SAML attribute

    Claim names with a . character

    If the incoming attribute has a . character in the name, the dot must be explicitly escaped using \. when defining the IDP attribute. For example, claim name https://example.com/groups must be entered as https://example\.com/groups.

  5. Save your changes and proceed to mapping the attributes to the authentication context.

    Attributes of your IDP correspond to the contents of the assertion (the XML received from the IDP).

    Example

    Here’s a SAML Response containing the <saml2:AttributeStatement> tag and attributes issued by IDP (in this case, a single username attribute with the value Joe):

    <?xml version="1.0" encoding="UTF-8"?>
    <saml2:Assertion ID="id1214053367877977596315632" IssueInstant="2022-01-07T09:14:27.545Z" Version="2.0"
        xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
        <saml2:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">http://www.okta.com/exk3ip7ehfTC60ReG5d7</saml2:Issuer>
        <saml2:Subject>
            <saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">test@mail.com</saml2:NameID>
            <saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
                <saml2:SubjectConfirmationData NotOnOrAfter="2022-01-07T09:19:27.545Z" Recipient="https://example.com/login">
            </saml2:SubjectConfirmation>
        </saml2:Subject>
        <saml2:Conditions NotBefore="2022-01-07T09:09:27.545Z" NotOnOrAfter="2022-01-07T09:19:27.545Z">
            <saml2:AudienceRestriction>
                <saml2:Audience>c7bhamiqs5kro24r4peg</saml2:Audience>
            </saml2:AudienceRestriction>
        </saml2:Conditions>
        <saml2:AuthnStatement AuthnInstant="2022-01-07T09:14:27.545Z" SessionIndex="id1641546867544.1585510482">
            <saml2:AuthnContext>
                <saml2:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</saml2:AuthnContextClassRef>
            </saml2:AuthnContext>
        </saml2:AuthnStatement>
        <saml2:AttributeStatement>
            <saml2:Attribute Name="username" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
                <saml2:AttributeValue
                    xmlns:xs="http://www.w3.org/2001/XMLSchema"
                    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">Joe
                </saml2:AttributeValue>
            </saml2:Attribute>
        </saml2:AttributeStatement>
    </saml2:Assertion>
    

Map IDP attributes to authentication context

If you’ve added custom attributes for an IDP, you need to make sure they are mapped to the authentication context. You can do it either from the IDP configuration page (as explained here) or use Data Lineage instead.

Default OIDC/SAML attributes are mapped out of the box.

  1. Go to Identity Data > Identity Providers and select an IDP from the list.

  2. Open the Mappings page. A standard attribute mapping for this IDP appears.

  3. Select Add mapping and map any custom IDP attributes to an existing authentication context attribute.

    Note

    If you need to create new authentication context attributes, read Setting up authentication context.

  4. Optionally, assign a post-authentication extension to modify your authentication context before issuing the token to the client. Attributes returned by the script do not need to be separately mapped to the authentication context.

  5. Save your changes. Your mapped custom attributes should now be shared in the ID token issued to your client application, given that the target application requests them (you can check this in Data Lineage).

Test your IDP

Prerequisites

  • Your IDP is enabled for user authentication.
  • Demo workspace is created with the Demo Portal connected.

Test

  1. Open the Demo Portal (Data lineage -> Demo Portal -> Launch).

  2. Select LOGIN TO DEMO APP.

  3. Select your configured IDP and, next, authenticate in IDP.

Result

Cloudentity displays the consent page that lists data scopes to be shared with the application. When you proceed to the application (ALLOW ACCESS), the PII data coming from Azure AD is delivered through the access token and the ID token generated by Cloudentity.

Read more

For information on granting and managing Cloudentity consents, see Cloudentity OAuth consents.

Updated: Jul 11, 2022