If you can't find the product or version you're looking for, visit support.ataccama.com/downloads

Keycloak Active Directory Integration

Use the following instructions to enable basic Single Sign-on via Keycloak with Azure Active Directory (AAD) as the identity provider using SAML.

In this article, we only cover authentication. In this case, when a user logs in to Ataccama for the first time, a user record is created in Keycloak with the user email address (as their username) and their first and last names, for use within Ataccama ONE.

These instructions assume that you have a fully-qualified-domain-name (FQDN) associated with the Ataccama Platform, which typically points to the gateway server’s or load balancer’s IP address.

Prepare Keycloak realm for integration with AD

Log in to the Keycloak Administration Console.
Open Ataccamaone realm in Keycloak.
Go to the Identity Providers.
From the dropdown list select SAML v2.0.
On the Add identity provider screen that opens, set up the Alias to 'saml'. This alias will be used in the redirect URL.

You can also add a Display Name which will be visible on the Ataccama Login page.
Make a note of the Redirect URI as it will be required later. Redirect URI should look something like https://<ataccama_platform_fqdn>/auth/realms/ataccamaone/broker/saml/endpoint, where saml matches the value of the Alias field.
Leave this window open as we will return to it later.

Your organization’s identity and access management team might require further information, as shown in the following example.

The following responses (or similar) can be provided:

Identifier / Entity ID: https://<ataccama_platform_fqdn>/auth/realms/ataccamaone.
User Identifier: The AD attribute you want to use as the login and identifier, for example, username on the client’s side.
Reply (ACS) URL (from the previous steps): https://<ataccama_platform_fqdn>/auth/realms/ataccamaone/broker/saml/endpoint.
Sign On URL: <leave blank>.
Relay State: <leave blank>.

After supplying this information to your IAM team, they should be able to create an XML file with the Identity Provider metadata. You will need this to complete the Keycloak realm integration.

Keycloak realm integration (continued)

Return to the open Keycloak Add Identity Provider page, and follow these steps:

Find the Import External IDP Config section at the bottom of the screen and paste the copied metadata link into the Import from URL field.
Select Import. If the format of the file is correct, you should receive:

The Single Sign-On Service URL is now populated. Other settings might have been changed too.
Select Save.

The First Login Flow is the process that is executed when a user logs in to Ataccama for the first time. In the scenario described here, a user record is created in Keycloak with the user email address as their username along with their first and last names, for use within Ataccama ONE.

Log in to the Keycloak Administration Console.
Ensure the Ataccamaone realm is selected.
In the left-hand menu, select Authentication.
On the Flows tab, select New.
Enter an Alias, for example, Simple Login Flow, and select Save.
With the new flow selected, select Add execution.
In Provider, find and select Create User If Unique.
Select Save.
In Requirement, select ALTERNATIVE.
The next time the user logs in, we want them to go directly to the platform. This involves the Browser Authentication flow:
- Log in to the Keycloak Administration Console.
- Ensure the Ataccamaone realm is selected.
- In the left-hand menu, select Authentication.
- In Flows, select Browser.
On the Identity Provider Redirector line, select Actions and then Config.
Enter the name of the identity provider, for example, saml, in both Alias and Default Identity Provider.
Select Save.

Single sign-on configuration

Log in to the Keycloak Administration Console.
Ensure the Ataccamaone realm is selected.
In the left-hand menu, select Identity Providers.
Select the name of the previously created identity provider, for example, saml:
In First Login Flow, select the flow that we created in the previous section, for example, Simple Login Flow.
In SAML Config, set NameID Policy Format to Email.
The SAML Config section should now look similar to this:

If so, select Save. If not, go back and edit as necessary.

Set up mappers

Log in to the Keycloak Administration Console.
Ensure the Ataccamaone realm is selected.
In the left-hand menu, select Identity Providers.
Select the name of the previously created identity provider, for example, saml.
Select the Mappers tab.
Select Create.
Enter a Name,for example, Surname mapper, and then select Attribute Importer as the Mapper Type.

The following screen appears. The important fields here are Attribute Name and User Attribute Name.

Attribute Name: For example, http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname.

User Attribute Name: lastName.

The value of Attribute Name must match the name of the attribute coming from the Azure AD claims.

There are a few ways to determine this. In the example XML, the claims are listed as part of the <fed:ClaimTypesOffered> section. However, this doesn’t necessarily mean that these attributes will be returned as part of the security handshake.

Refer to Map the claims to retrieve and decode the claims as they are returned during the login process.

Use camel case for User Attribute Name.

Repeat the same for the first name:
- Attribute Name: For example, http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname.
- User Attribute Name: firstName.

Map the claims

This section provides a method for capturing and decoding the claims that are returned by Azure Active Directory as part of the login process. For the purpose of this guide, we are using Google Chrome as our browser.

For this method to work, a user needs to be set up in Azure AD with the correct permissions (for example, AD Group) that provides the user with access to the Ataccama Platform.

Log in to the Keycloak Administration Console.
Ensure the test user does not already have a record in Keycloak. If the record exists, make a separate note of the associated roles and delete the user record.
Open an Incognito Google Chrome window (Ctrl+Shift+N).
Open Developer Tools (Ctrl+Shift+I).

For ease of use, move the console to the bottom of the window. Select the more options menu and then the third Dock side option.
Ensure the Preserve log option is selected.
Attempt to log in to Ataccama, for example, by trying to access https://<ataccama_platform_fqdn>/.
In the console, find the Azure AD reply that contains the SAMLResponse.

Copy the entire SAMLResponse (here starting with PHNhbWxwOlJlc3BvbnNlIElEPSJfYTE0ZWY2ODQtZmEwMy00OT…) and use a website such as www.samltool.com/decode.php to decode it. After reformatting the XML, the (anonymised) response should look similar to this:

Example SAML response

<?xml version="1.0" encoding="UTF-8"?>
<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" ID="_a14ef684-fa03-4990-a427-4dfb85478533" Version="2.0" IssueInstant="2019-07-02T07:19:35.874Z" Destination="https://<ataccama_platform_fqdn>/auth/realms/ataccamaone/broker/saml/endpoint" InResponseTo="ID_9338c443-1ecd-4f6f-8a24-4622ded87ca7">
   <Issuer xmlns="urn:oasis:names:tc:SAML:2.0:assertion">https://sts.windows.net/97160e56-eb00-44fe-b31d-0d6d351c636d/</Issuer>
   <samlp:Status>
      <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success" />
   </samlp:Status>
   <Assertion xmlns="urn:oasis:names:tc:SAML:2.0:assertion" ID="_3ae03e36-e461-4f61-b204-720f19f17300" IssueInstant="2019-07-02T07:19:35.858Z" Version="2.0">
      <Issuer>https://sts.windows.net/97160e56-eb00-44fe-b31d-0d6d351c636d/</Issuer>
      <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
         <SignedInfo>
            <CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
            <SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256" />
            <Reference URI="#_3ae03e36-e461-4f61-b204-720f19f17300">
               <Transforms>
                  <Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature" />
                  <Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
               </Transforms>
               <DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256" />
               <DigestValue>FnfGJo8O5APMB4PmFvtZTB576PLZIeb9UVpjblYU7Kk=</DigestValue>
            </Reference>
         </SignedInfo>
         <SignatureValue>J9jhAHU4OH5UygNPVA…VmpGpZusSoCrRxJH6ysswQ==</SignatureValue>
         <KeyInfo>
            <X509Data>
<X509Certificate>MIIC8DCCAdigAwIB…r645jGSdHxtK</X509Certificate>
            </X509Data>
         </KeyInfo>
      </Signature>
      <Subject>
         <NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">adrian.anderson@somewhere.com</NameID>
         <SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
            <SubjectConfirmationData InResponseTo="ID_1234…7ca7" NotOnOrAfter="2019-07-02T07:24:35.858Z" Recipient="https://<ataccama_platform_fqdn>/auth/realms/ataccamaone/broker/saml/endpoint" />
         </SubjectConfirmation>
      </Subject>
      <Conditions NotBefore="2019-07-02T07:14:35.858Z" NotOnOrAfter="2019-07-02T08:19:35.858Z">
         <AudienceRestriction>
            <Audience>https://<ataccama_platform_fqdn>/auth/realms/ataccamaone</Audience>
         </AudienceRestriction>
      </Conditions>
      <AttributeStatement>
         <Attribute Name="http://schemas.microsoft.com/identity/claims/tenantid">
            <AttributeValue>1234…636d</AttributeValue>
         </Attribute>
         <Attribute Name="http://schemas.microsoft.com/identity/claims/objectidentifier">
            <AttributeValue>ad00b932-…-69a90d9eadaf</AttributeValue>
         </Attribute>
         <Attribute Name="http://schemas.microsoft.com/identity/claims/displayname">
            <AttributeValue>Anderson, Adrian</AttributeValue>
         </Attribute>
         <Attribute Name="http://schemas.microsoft.com/identity/claims/identityprovider">
            <AttributeValue>https://sts.windows.net/1234...636d/</AttributeValue>
         </Attribute>
         <Attribute Name="http://schemas.microsoft.com/claims/authnmethodsreferences">
            <AttributeValue>http://schemas.microsoft.com/ws/2008/06/identity/authenticationmethod/password</AttributeValue>
            <AttributeValue>http://schemas.microsoft.com/ws/2008/06/identity/authenticationmethod/windows</AttributeValue>
         </Attribute>
         <Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname">
            <AttributeValue>Adrian</AttributeValue>
         </Attribute>
         <Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname">
            <AttributeValue>Anderson</AttributeValue>
         </Attribute>
         <Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress">
            <AttributeValue>Adrian.Anderson@somewhere.com</AttributeValue>
         </Attribute>
         <Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name">
            <AttributeValue>Adrian.Anderson@somewhere.com.au</AttributeValue>
         </Attribute>
      </AttributeStatement>
      <AuthnStatement AuthnInstant="2019-07-02T07:19:35.101Z" SessionIndex="_3ae03e36-e461-4f61-b204-720f19f17300">
         <AuthnContext>
            <AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:Password</AuthnContextClassRef>
         </AuthnContext>
      </AuthnStatement>
   </Assertion>
</samlp:Response>

The attribute names can be clearly seen in the response. The full value from between the double-quotes is required.

Check the resulting user record in Keycloak. If the mappers were not set up correctly, update the mappers, delete the user record, and log in to the platform again.

Map the roles

Before proceeding with this section, make sure you have completed setting up the identity-related claims (see Set up mappers).

To get mappers for identity providers, see Keycloak Admin REST API documentation.

Create a counterpart in Keycloak for each role in Active Directory, for example, AD_ROLE_ADMIN.
Map those roles to Ataccama-specific roles as required.
Navigate to Identity Provider > Identity Provider Mappers.

Identify the claim as groups from AD. See the example:

<Attribute Name="http://schemas.microsoft.com/ws/2008/06/identity/claims/groups"><AttributeValue>a8dfc3d4-c0c3-48f1-9d8e-157c645ef26e</AttributeValue></Attribute>

Use SAML Attribute to Role, and fill in as required. Based on the previous example, this would be:
- Attribute Name: http://schemas.microsoft.com/ws/2008/06/identity/claims/groups.
- Attribute Value: a8dfc3d4-c0c3-48f1-9d8e-157c645ef26e.
- Role: AD_ROLE_ADMIN.
Save the mapper.
Repeat these steps for as many groups as needed.

Was this page useful?

Keycloak Active Directory Integration

Prepare Keycloak realm for integration with AD

Keycloak realm integration (continued)

Set up the first login flow

Single sign-on configuration

Set up mappers

Map the claims

Map the roles