Child pages
  • OpenAM 13 and ADFS3 (Windows Server 2012 R2) configuration
Skip to end of metadata
Go to start of metadata

General

This document describes how to configure OpenAM 13 as a "Service Provider" and Microsoft Active Directory Federation Server (ADFS3) as an "Identity Provider" through SAML federation. Thanks and acknowledgements to Andrew Potter as the author of "OpenAM 12 and ADFS3 (Win2012 R2) configuration" and all the ADFS configuration reported into this guide.

Use cases

Actors:

  • OpenAM
  • ADFS
  • Browser

Use cases:

  • A user must be able to login to client applications, federated with OpenAM as IDP, using profile credentials stored within ADFS.
  • A user who is logged to a Windows machine must be able to launch the OpenAM user Profile Page without resubmitting his user credentials.

In the first use case OpenAM has to roles: IDP and SP. In the first role client applications act as SP federated with OpenAM as IDP, whereas in the second role ADFS is an IDP federated with OpenAM as SP.

To achieve those use cases scenario, we will use a SAML federation to establish a trusted link between the 2 entities.

The UML diagram below describes the flow of the federated authentication process.

 

 

Figure 1: UML diagram Federation Process

Explanation of above UML diagram

  • Step 1: User tries to access a resource on the SP (OpenAM server). This webpage will try to detect if the user has already got an OpenAM session, if not the user will be redirected to the IDP (ADFS) server.
    A SAML Authentication Request message is generated and sent along with the redirection (Step 2 and 3)
  • In Step 3 the IDP server receives the request. If the client browser has already has an ADFS session, step 4 and 5 are omitted, otherwise an HTTP 401 will be issued to the client which is basically an HTTP authentication request.
  • Step 5 will return the authentication response. In case of NTLM/Kerberos this is an automated process via the SPNEGO protocol.
  • Step 6: the IDP server receives the authentication response and when successful it will generate a SAML response.
  • Step 7: Client browser is redirected back to the OpenAM server where is decodes the SAML response and issues an OpenAM token.

Prerequisites

This section describes the prerequisites for implementing OpenAM and ADFS to support the use cases described earlier.

One important requirement for the solution is that both environments need to be SSL configured. For the proof of concept the web sites were configured with self signed certificates to support this. 

ADFS Requirements

For this proof of concept the following software was used to setup the server with ADFS:

  • Windows Server 2012 R2, Enterprise Edition
  • Internet Information Services (IIS)
  • Microsoft .NET Framework
  • Active Directory Federation Services 

The installation of Microsoft Active Directory Federation Services is out of scope for this document. 

OpenAM Requirements

For this proof of concept the following software was used.

  • Debian 8
  • Tomcat 7 (with SSL configuration)
  • Java JDK 7
  • OpenAM 13.0.0
  • OpenDJ 3

The installation of Tomcat with SSL is out of scope for this document but it is very important that Tomcat is properly configured with SSL. 

Implementation Steps

The following sections describe the steps to undertake to implement SSO Federation between OpenAM and Microsoft Active Directory.

Please note that if you want to familiarize yourself with Microsoft Active Directory Federation Server, there is a "Getting Started" guide available at https://technet.microsoft.com/en-us/library/dn452410.aspx

OpenAM as SP e.g. domain: sp.domain1.local
ADFS as IDP e.g. domain: idp.domain2.local

SSL Certificates

There is a requirement that all data between the Identity Provider and Service Provider is signed and encrypted, then you need to generate certificates for signing and encryption. ADFS can be quite picky about this so you should definitely run through these steps!

On the idp.domain2.local server these certificates are automatically generated by the ADFS installation process.

On the sp.domain1.local server you need to create them manually. Again, to generate certificates you can use the Java keytool tool but KeyStore Explorer is more convenient.

OpenAM uses its own keystore file. In our test environment the OpenAM configuration files are stored in the directory ~/openam. This folder was configured during the installation of OpenAM.

In the folder d~/openam/openam you will find the default keystore.jks file. You can either create a whole new keystore or use this one.

The default password is "changeit".

Use the Keystore Explorer to open the OpenAM keystore.
Click on Tools | Generate new Keypair, to generate a new certificate.

Use the details from the below table to create a Token Signing Certificate and a Token Encryption Certificate.

Name

Value

Algorithm (RSA or DSA)

RSA

Key size

2048

Signature Algorithm

SHA.1 with RSA

Name

CN=sso_ts,OU=domain1,O=local

Alias

SSO_TS

Password

changeit

Name

Value

Algorithm (RSA or DSA)

RSA

Key size

2048

Signature Algorithm

SHA.1 with RSA

Name

CN=sso_te,OU=domain1,O=local

Alias

SSO_TE

Password

changeit

  

After the certificate is created, export the certificate in order to import the public key on the ADFS server. To export the certificate, double-click on the certificate and click on PEM, then click Export. Save the certificates to ~/sso_ts.cer and ~/sso_te.cer

Also make sure that the Tomcat SSL certificate needs to be exported into a cer file.

To do this you can also use the KeyTool Explorer and export the public key into sso01.cer. Please restart OpenAM after importing all certificates and keystore.

On the idp.domain2.local server import the public key certificates (sso01.cer, sso_ts and sso_te). To do this, copy the .cer files onto the ADFS server and start the Microsoft Management Console (MMC.EXE)

Via File | Add/Remove SnapIn | Add, find the Certificates snapin and click on Add.



Then for each .cer file right click on Personal/certificates | Import and select the .cer files.

This will import the certificates in the Personal store.

Please note that because these certificates are all Self Signed certificates these will not be Trusted. On a production environment you will need to have certificates which have been signed by a trusted CA (Certificate Authority) but for a proof of concept you can use a workaround by adding the certificates to the "Trusted Root Certification Authorities". This can be done similarly as importing into the personal store. Right click on "Trusted Root Certification Authorities / Certificates" and click Import to import each .cer file.

Now you also need to export the Microsoft ADFS server certificates and Import them onto the OpenAM server.

To export the ADFS certificates launch the ADFS 2.0 Management Tool: 


In the ADFS2.0 | Service | Certificates screen you will find all the required certificates in one place.

For each of the three certificates, double click to open the Certificates window.

Click on the Details tab and then click on the Copy to File button. This will start the export wizard.

Click "No do not export private key" and select the "DER Encoded X.509 (.cer)" encoding.

Save the files as

  • ADFS.cer
  • ADFS_TE.cer
  • ADFS_TS.cer

Copy these .cer files over to the OpenAM server.

To import the files on the OpenAM server you can use the KeyStore Explorer tool. Please note that the files need to be imported in both OpenAM keystore and the Tomcat Keystore.

Also because these certificates are self-signed they have to be imported in the CACerts keystore of the Java JRE/JDK being used. Normally the CACerts store is located at:

$JAVA_HOME/jre/lib/security/cacerts

Setting up OpenAM as Service Provider

  1. Login to OpenAM as full admin user (eg. amAdmin);
  2. Select the realm where you want to create the federation;
  3. Click on "Create SAML v2 Providers";
  4. Click on "Create Hosted Service Provider";
    1. Make sure the identifier name looks something like this: https://sp.domain1.local/openam and remove the port number if exists to avoid naming problems in further steps;
    2. Select a "Circle of trust" (it defines a set of services and identity providers which trust each other) or create a new one;
    3. Make sure the checkbox "Use default attribute mapping from Identity Provider" is active;
    4. Click on the button "Configure" in the upper right. Rejects if you will be asked if you want to create now a remote identity provider;
  5. Click on the "Federation" tab and select the service provider just created (e.g. https://sp.domain1.local/openam);
    1. Assertion Content Tab:
      1. Tick "Authentication Requests Signed" and "Assertions Signed";
      2. Certificate Aliases - Signing: Add sso_ts;
      3. Certificate Aliases - Encryption: Add sso_te;
      4. Save;
    2. Assertion Processing Tab:
      1. Attribute Map: delete all attributes;
      2. Attribute Map: add the following value: UPN=uid;
      3. Auto Federation: tick the "Enabled" checkbox
      4. Auto Federation: fill the attribute input with the following value: uid
      5. Account Mapper: tick "Use Name ID as User ID";
      6. Save;
    3. Services Tab:
      1. Assertion Consumer Service:
        1. Untick "HTTP-Artifact" as default and change the index field to 2;
        2. Tick "HTTP-POST" as default and index 0;
        3. Untick "PAOS" as default and change the index field to 1;
      2. Save;

Register a remote ADFS Identity Provider on OpenAM

ADFS Steps:

First generate the ADFS output by navigating to:

https://idp.domain2.local/federationmetadata/2007-06/Federationmetadata.xml

and save it as a file (e.g. idp.xml).

Then open the XML file and remove the following sections entirely (note that ADFS generates the xml all on one line so it can be tricky to edit this file correctly):

Ds:Signature
RoleDescription
SPSSODescriptor

Make sure you remove all SPSSODescriptor tags.

This will only leave the IDPSSODescriptor.

OpenAM Steps:

  1. Login to OpenAM as full admin user (eg. amAdmin);
  2. Select the same realm where you created the previous federation;
  3. Click on "Create SAML v2 Providers";
  4. Click on "Register Remote Identity Provider";
    1. Upload the metadata (idp.xml) generated in the previous step;
    2. Select the same "Circle of trust" previously defined;
    3. Click on the button "Configure" in the upper right.
  5. Click on the "Federation" tab and select the identity provider just created (e.g. http://idp.domain2.local/adfs/services/trust);
    1. Assertion Content Tab:
      1. Add the following new values within NameID Format List:
        1. "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified";
        2. "urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName";
        3. "urn:oasis:names:tc:SAML:1.1:nameid-format:WindowsDomainQualifiedName";
        4. "urn:oasis:names:tc:SAML:2.0:nameid-format:kerberos";
      2. Save;
  6. Make sure that https://<sp.domain1.local>/openam and http://<idp.domain2.local>/adfs/services/trust are under the same COT.

Register a remote OpenAM Service Provider on ADFS

Configuring the Active Directory Federation Server

Microsoft 2012 R2 Enterprise server includes the ADFS component via the "Active Directory Federation Services" server role. 

The installation of the ADFS role automatically generates the necessary certificates for the default website but also for the Token Signing and Token Encryption. Please note that these certificates are self signed certificates and therefore not trusted by others.

In order to configure the Trust relationship in ADFS you need to add a Relying Party Trust (to the OpenAM server) via the ADFS Management tool:



There a 3 ways to creating a Relying Party Trust. One of them is importing the metadata XML files just like you have done for OpenAM. However ADFS lets us use the OpenAM metadata URL to obtain the metadata dynamically. So selecting the first option and use the following URL

https://sp.domain1.local/openam/saml2/jsp/exportmetadata.jsp 

* If you created the federation within a "Sub Realm", do not forget to append it at the end of the above URL as query param: ?realm=NameSubRealm

This will import the Relying Party Trust.

After importing the metadata please review the following properties

  • On the Encryption Tab, please verify that the sso_te Certificate is selected.
  • On the Signature Tab, please verify that the sso_ts Certificate is selected.
  • On the Advanced Tab, please make sure that the SHA1 algorithm is selected.

After creating the Relying Party Trust you also need to define the claim rules to define what information to send to this trusted provider. In our proof of concept I used the Windows Account Name (SAM-Account-Name) and a bundle of other AD attributes to be sent over to OpenAM. In order to do this you need to create two Claim rules in the Edit Claim Rules wizard.

First you need to create a generic LDAP rule where you have to map the internal Active Directory LDAP attributes to Claim Types.

  1. Highlight the OpenAM Relying Party you have just created, click "Edit Claim rules".
  2. In the "Issuance Transform Rules" tab of the dialog box that opens, click "Add Rule".
  3. Select "Send LDAP Attributes as Claims", click Next.
  4. Provide a rule name, such as "samacctname".
  5. Select "Active Directory" as the Attribute Store
  6. Map some AD attributes.  At a minimum you must provide SAM-Account-Name mapped to sAmAcctName.  In our case I mapped a few additional LDAP (i.e. AD) attributes to the outgoing claims as well: 
     
  7. click Finish to return to the 'Edit Claim Rules' dialog box.

These outgoing claims appear as SAML Attributes in the SAML payload.

The only important one is the SAM-Account-Name attribute as we'll use this in the second rule described below.  The other attributes will appear as SAML attributes in the assertion and can be selected according to your needs.

The second rule is very custom. We need to send the SAML Name Identifier (NameID) as part of the SAML assertion. Although ADFS allows you to create Claim Rules via a Wizard and also create "Transform Claim Rules" where you can easily transform incoming claims and assign different attributes into it, it does not work with OpenAM. Mainly because we need a "spname" qualifier to be present in the SAML assertion. Therefore you need to create a custom rule. ADFS provides the option to define custom rules that can be used to determine the behaviour of identity claims with the claim rule language.  In this scenario I am going to use the sAmAcctName claim we have specified in the previous as the NameID, and add the SPNameQualifer attribute (which should match the name of the OpenAM Service Provider as it is defined in ADFS).

  1. From the Edit Claims Rules dialog box, click "Add Rule"
  2. Select 'Send Claims using a Custom Rule' template
  3. Name the rule, such as 'namequalifier'
  4. Enter the rule using the script below, as per the image below
  5. Click Finish
  6. Click Ok

  

c:[Type == "sAmAcctName"]
 => issue(Type = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier", 
Issuer = c.Issuer, OriginalIssuer = c.OriginalIssuer, Value = c.Value, ValueType = c.ValueType, 
Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/format"] = "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified", Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/namequalifier"] = "<Federation Service identifier>", Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/spnamequalifier"] = "https://sp.domain1.local/openam");

...where <Federation Service identifier> is the value specified in the ADFS "Federation Service Properties" window. This might look something like https://idp.domain2.local/adfs/services/trust
Take care to enter the name exactly as it appears in the Federation Service Properties window.

This "Claims Language" looks complicated. In essence it is mapping the previously defined "sAmAcctName" claim to this claim through these rules. These rules define this claim with a Type (http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier) that ADFS knows how to format as a NameID element in a SAML Assertion. The various Properties are emitted by ADFS as XML attributes to the NameID element - and include the necessary spnamequalifier attribute. Also note that I'm using the "unspecified" NameID format which we'll need to know a bit later on.

OpenAM User Profile Authentication

The mapping attribute used to federate ADFS and OpenAM is the UID, then before testing the single sign-on (SSO) we must make sure that we have a user with the same UID on both entities.

A very useful alternative option is to configure the OpenAM Authentication so that in case of missing UID it will be created dynamically or ignored allowing access though. You can change those options by going to Realm -> Authentication -> Settings -> User Profile Tab.

Testing SSO Use Cases

Use case N.1

Description: a user must be able to login to client applications, federated with OpenAM as IDP, using profile credentials stored within ADFS.

Client Application e.g.: https://app.domain1.local

Assuming that you already have a client application as SP federated with OpenAM as IDP, this last one will check if you have been authenticated already and if not it will redirect you back to the ADFS IDP. On the IDP you need to authenticate to ADFS. For the moment it is not using IWA (Integrated Windows Authentication via NTLM or Kerberos) yet. After logon you will be redirected back to the Client Application where federation takes place and your session will be created.

You can use the following URL to trigger the above use case:

https://sp.domain1.local/openam/saml2/jsp/spSSOInit.jsp?metaAlias=/sp&idpEntityID=http://idp.domain2.local/adfs/services/trust&NameIDFormat=urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified&RelayState=https://app.domain1.local

In case of federation within a specific realm metaAlias is equals to: metaAlias=/{realmName}/sp

Use case N.2

Description: a user who is logged to a Windows machine must be able to launch the OpenAM user Profile Page without resubmitting his user credentials.

Configuring the Client (IWA AuthN)

On the client machine you need to configure the user’s Internet Explorer settings so the browser trusts the OpenAM federation server. This is done by adding the sp.domain1.local federation server into the Local Internet sites.

To configure the browser settings to trust the sp.domain1.local federation server:

  • Start Internet Explorer;
  • On the Tools menu, click Internet options;
  • On the security tab, client the Local Internet icon, and then click sites;
  • Click Advanced, and the OpenAM URL

ADFS offers various authentication methods, such as forms authentication, which will always offers a user/password screen. But it also offers IWA to authenticate internally. If you would navigate directly to the https://idp.domain2.local/adfs/ls/IdpInitiatedSignOn.aspx page you will have the opportunity to logon only to ADFS or Logon to ADFS and redirect directly to one of the configured Service Provider Trusts.

There is also a way of doing this without the Sign-In and go directly to one of the configured service providers by providing the service provider as a query parameter:

https://idp.domain2.local/adfs/ls/IdpInitiatedSignOn.aspx?loginToRp=https://sp.domain1.local/openam