SAML Federation in AM/OpenAM

This book provides information on SAML2 federation in AM/OpenAM and includes help on configuring federation, managing SAML certificates and manipulating metadata for IdPs and SPs.


What federation standards does AM/OpenAM support?

The purpose of this article is to provide information on the supported federation standards in AM/OpenAM.

Overview

This article provides information on the following federation standards:

OAuth 2.0 support

Grant Type AM 6 AM 5.5 AM 5/5.1 OpenAM 13.x OpenAM 12.x Documentation Reference
Authorization code Yes Yes Yes Yes Yes OAuth 2.0 Guide › Introducing OAuth 2.0 › OAuth 2.0 Authorization Server
Implicit Yes Yes Yes Yes Yes OAuth 2.0 Guide › Introducing OAuth 2.0 › OAuth 2.0 Authorization Server
Resource Owner Password Credentials Yes Yes Yes Yes Yes OAuth 2.0 Guide › Introducing OAuth 2.0 › OAuth 2.0 Authorization Server
Client Credentials Yes Yes Yes Yes Yes OAuth 2.0 Guide › Introducing OAuth 2.0 › OAuth 2.0 Authorization Server
Client Type            
Confidential Yes Yes Yes Yes Yes OAuth 2.0 Guide › Using OAuth 2.0 › OAuth 2.0 Client Administration Endpoint
Public Yes Yes Yes Yes Yes OAuth 2.0 Guide › Using OAuth 2.0 › OAuth 2.0 Client Administration Endpoint
Credential Type            
Access token Yes Yes Yes Yes Yes OAuth 2.0 Guide › Introducing OAuth 2.0 › OAuth 2.0 Authorization Server
Refresh token Yes Yes Yes Yes Yes OAuth 2.0 Guide › Introducing OAuth 2.0 › OAuth 2.0 Authorization Server
Additional Features            
Bearer Token Usage Yes Yes Yes Yes Yes Reference › Supported Standards (RFC 6750)
Assertion Framework Yes Yes Yes Yes Yes Reference › Supported Standards (RFC 7521)
SAML 2.0 Bearer Assertion Profiles Yes Yes Yes Yes Yes Reference › Supported Standards (RFC 7522)
JSON Web Token (JWT) Profile Yes Yes Yes Yes Yes Reference › Supported Standards (RFC 7523)
Proof-of-Possession Key Semantics for JWT Yes Yes Yes -- -- Reference › Supported Standards (RFC 7800)
Dynamic Client Registration Yes Yes -- -- -- Reference › Supported Standards (RFC 7591)
Remote Consent Service Support Yes Yes -- -- -- OAuth 2.0 Guide › OAuth 2.0 Remote Consent Service

OpenID Connect 1.0 support

Specification AM 6 AM 5.x OpenAM 13.x OpenAM 12.x * Documentation Reference
OpenID Connect Core 1.0 Yes Yes Yes -- Reference › Supported Standards
OpenID Connect Discovery 1.0 Yes Yes Yes -- Reference › Supported Standards
OpenID Connect Dynamic Client Registration 1.0 Yes Yes Yes -- Reference › Supported Standards
OpenID Connect Session Management 1.0 Yes Yes Yes -- Reference › Supported Standards
OAuth 2.0 Multiple Response Type Encoding Practices Yes Yes Yes -- Reference › Supported Standards
OAuth 2.0 Form Post Response Mode Yes Yes Yes -- Reference › Supported Standards
OpenID Connect Basic Client Implementer's Guide 1.0 Yes Yes Yes -- Reference › Supported Standards
OpenID Connect Implicit Client Implementer's Guide 1.0 Yes Yes Yes -- Reference › Supported Standards

 * The OIDC specifications are partially supported in OpenAM 12.x but are not fully compliant.

SAML 2.0 support

Profile AM 6 AM 5.x OpenAM 13.x OpenAM 12.x Documentation Reference
Web Browser SSO Profile Yes Yes Yes Yes  
Enhanced Client or Proxy (ECP) Profile Yes Yes Yes Yes SAML v2.0 Guide › Implementing SAML v2.0 Using the AM Console › Configuring for the ECP Profile
Identity Provider Discovery Profile Yes Yes Yes Yes SAML v2.0 Guide › Implementing SAML v2.0 Using the AM Console › Deploying the Identity Provider Discovery Service
Single Logout Profile Yes Yes Yes Yes SAML v2.0 Guide › Implementing SAML v2.0 Using the AM Console › Implementing SAML v2.0 Single Sign-On and Single Logout
Name Identifier Management Profile Yes Yes Yes Yes SAML v2.0 Guide › Implementing SAML v2.0 Using the AM Console › Changing Federation of Persistently Linked Accounts
Artifact Resolution Profile Yes Yes Yes Yes SAML v2.0 Guide › Reference › Services
Assertion Query/Request Profile Yes Yes Yes Yes SAML v2.0 Guide › Reference › Assertion Cache
Name Identifier Mapping Profile Yes Yes Yes Yes SAML v2.0 Guide › Reference › NameID Mapping
SAML Attribute Profiles
  • Basic Attribute Profile
  • X.500/LDAP Attribute Profile
  • UUID Attribute Profile
  • DCE PAC Attribute Profile
  • XACML Attribute Profile
Yes Yes Yes Yes SAML v2.0 Guide › Reference › Attribute Mapper
Binding          
SAML SOAP Binding Yes Yes Yes Yes Reference › Service Endpoints › Service Console JSP Endpoints
Reverse SOAP (PAOS) Binding Yes Yes Yes Yes SAML v2.0 Guide › Implementing SAML v2.0 Using the AM Console › Configuring for the ECP Profile
HTTP Redirect Binding Yes Yes Yes Yes SAML v2.0 Guide › Implementing SAML v2.0 Using the AM Console › JSP Pages for SSO and SLO
HTTP POST Binding Yes Yes Yes Yes SAML v2.0 Guide › Implementing SAML v2.0 Using the AM Console › JSP Pages for SSO and SLO
HTTP Artifact Binding Yes Yes Yes Yes SAML v2.0 Guide › Implementing SAML v2.0 Using the AM Console › JSP Pages for SSO and SLO
SAML URI Binding -- -- -- --  
Assertion Signature Algorithms          
rsa-sha1 Yes Yes Yes Yes Reference › Supported Standards
rsa-sha256 Yes Yes Yes Yes Reference › Supported Standards
rsa-sha384 Yes Yes Yes Yes Reference › Supported Standards
rsa-sha512 Yes Yes Yes Yes Reference › Supported Standards
Assertion Encryption Algorithms          
aes128-cbc Yes Yes Yes Yes Reference › Supported Standards
aes192-cbc Yes Yes Yes Yes Reference › Supported Standards
aes256-cbc Yes Yes Yes Yes Reference › Supported Standards
tripledes-cbc Yes Yes Yes Yes Reference › Supported Standards
QueryString Signature Algorithms *          
rsa-sha1 Yes Yes Yes Yes Reference › Supported Standards
rsa-sha256 Yes Yes Yes -- Reference › Supported Standards
rsa-sha384 Yes Yes Yes -- Reference › Supported Standards
rsa-sha512 Yes Yes Yes -- Reference › Supported Standards
dsa-sha1 Yes Yes Yes Yes Reference › Supported Standards
ecdsa-sha1 Yes Yes Yes -- Reference › Supported Standards
ecdsa-sha256 Yes Yes Yes -- Reference › Supported Standards
ecdsa-sha384 Yes Yes Yes -- Reference › Supported Standards
ecdsa-sha512 Yes Yes Yes -- Reference › Supported Standards

* Support for all the listed QueryString Signature Algorithms was introduced in OpenAM 12.0.3.

SAML 1.x support

Profile AM 6 AM 5.x OpenAM 13.x OpenAM 12.x Documentation Reference
IdP-initated SSO Browser Post Yes Yes Yes Yes SAML v1.x Guide › About SAML v1.x
IdP-initated SSO Browser Artifact Yes Yes Yes Yes SAML v1.x Guide › About SAML v1.x
Non-normative SP-initiated scenario (called “destination-first”) Yes Yes Yes Yes SAML v1.x Guide › About SAML v1.x

WS-Federation 1.1 support

Protocol AM 6 AM 5.x OpenAM 13.5 OpenAM 13.0 OpenAM 12.x Documentation Reference
WS-Federation Passive Requestor Profile for SP-initiated SSO Yes Yes Yes Yes Yes How do I configure AM (All versions) or OpenAM 13.5.x as an Identity Provider for Microsoft Office 365 and Azure using WS-Federation?WS-Federation Custom SP Attribute Mapper in OpenAM and Using OpenAM as SharePoint 2010/2013 Trusted Identity Token Issuer
WS-Federation Active Requestor Profile Yes Yes Yes  -- --  

Web Services Security support

Specification Namespace AM 6 AM 5.x OpenAM 13.x OpenAM 12.x Documentation Reference
SOAP 1.1 Schema for the SOAP/1.1 envelope Yes Yes Yes Yes API Javadoc › Class SAMLConstants
SOAP 1.2 Schema defined in the SOAP Version 1.2 Part 1 specification Yes Yes Yes Yes API Javadoc › Class SAMLConstants
WS-Trust 2005 Web Services Trust Language (WS-Trust) -- -- -- Yes  
WS-Trust 1.3 WS-Trust 1.3 -- -- -- Yes  
WS-Trust 1.4 WS-Trust 1.4 Yes Yes Yes Yes Security Token Service Guide

See Also

FAQ: SAML federation in AM/OpenAM

FAQ: SAML certificate management in AM/OpenAM

How does AM/OpenAM (All versions) use account mapping to identify the end user from a SAML Assertion?

How do I know which binding to use for SAML2 federation in AM/OpenAM (All versions)?

How do I configure AM/OpenAM (All versions) to integrate with Microsoft Office 365 using SAML2?

How do I configure AM (All versions) or OpenAM 13.5.x as an Identity Provider for Microsoft Office 365 and Azure using WS-Federation?

How do I perform common OAuth 2.0 tasks using curl commands with the standard endpoints in AM/OpenAM (All versions)?

How do I request further information (such as client_id or uid) for an OAuth 2.0 access token in AM/OpenAM (All versions)?

FAQ: OAuth 2.0 in AM/OpenAM

SAML Federation in AM/OpenAM

OAuth 2.0 in AM/OpenAM

Related Training

N/A

Related Issue Tracker IDs

N/A


Configuring Federation


How do I configure the SAML2 Authentication module for Local Account Linking in AM (All versions) and OpenAM 13.x?

The purpose of this article is to provide a video demonstration that walks you through configuring both the identity provider (IdP) and service provider (SP) for federation using the SAML2 Authentication module as part of a complex login chain in AM/OpenAM.

Configuring federation using the SAML2 Authentication module for Local Account Linking

Note

This video demonstration uses OpenAM 13.0; although the appearance has changed between AM aand OpenAM 13.x, the principles and processes are still applicable. In AM, the options under Federation are now under Realms > [Realm Name] > Applications > SAML.

This video demonstration was recorded in HD and is best viewed in Full Screen mode:

Contributed by David Luna

Video Transcript

Click here to download a transcript of this video tutorial. 

See Also

ohnomorejuzzoblogs - Example Configuration - Local Account Linking

How do I configure the SAML2 Authentication module for Auto Federation in AM (All versions) and OpenAM 13.x?

How do I set up the SAML2 Authentication module using Integrated Mode in AM (All versions) and OpenAM 13.x?

How does AM/OpenAM (All versions) use account mapping to identify the end user from a SAML Assertion?

FAQ: SAML federation in AM/OpenAM

SAML Federation in AM/OpenAM

Authentication and Single Sign-On Guide › Implementing Authentication › SAML2 Authentication Module

SAML v2.0 Guide › Implementing SAML v2.0 Using the AM Console › Implementing SAML v2.0 Single Sign-On and Single Logout

Authentication and Single Sign-On Guide › Implementing Authentication › Device ID (Match) Authentication Module

Authentication and Single Sign-On Guide › Implementing Authentication › OATH Authentication Module

Related Training

N/A

Related Issue Tracker IDs

N/A


How do I set up the SAML2 Authentication module using Integrated Mode in AM (All versions) and OpenAM 13.x?

The purpose of this article is to provide information on setting up federation with the SAML2 Authentication module in AM/OpenAM, where AM/OpenAM is the hosted SP. This information applies when you want to configure SAML2 SSO in integrated mode.

Setting up federation in integrated mode

Note

The process to set up federation with the SAML2 authentication module is fully documented in SAML v2.0 Guide › Implementing SAML v2.0 Single Sign-On in Integrated Mode.

However, if you are confident about setting up federation in integrated mode without referring to the documentation, here are the high-level steps (including the key changes you must make that are not so obvious without referring to the documentation):

  1. Set up federation as usual with AM/OpenAM as the hosted SP.
  2. Create the SAML2 authentication module and include it in an authentication chain.
  3. Select the SP entity provider:
    • AM 6 and later console: navigate to Realms > [Realm Name] > Applications > Federation > Entity Providers and click the name of the entity provider that is of type Hosted SP.
    • AM 5.x console: navigate to: Realms > [Realm Name] > Applications > SAML > Circle of Trust Configuration > Entity Providers and click the name of the entity provider that is of type Hosted SP.
    • OpenAM 13.x console: navigate to: Federation > Circle of Trust Configuration > Entity Providers and click the name of the entity provider that is of type Hosted SP.
  4. Navigate to Services > Assertion Consumer Service and change the following consumer service locations in the SP configuration:
    • Change the location of the HTTP-Artifact consumer service to use AuthConsumer rather than Consumer. For example, if the location is http://sp.example.com:8080/openam/Consumer/metaAlias/sp, change it to http://sp.example.com:8080/openam/AuthConsumer/metaAlias/sp.
    • Change the location of the HTTP-POST consumer service to use AuthConsumer rather than Consumer as per the HTTP-Artifact consumer service.
    These changes are necessary and imply that you cannot have both the SAML2 authentication module and non-integrated federation on the same SP.
  5. Notify the IdP of these new endpoints if relevant. 
Note

You do not need to change the location of the PAOS service because integrated mode does not support the PAOS binding.

  1. Test your configuration. First, clear your browser's cache and cookies. Then, attempt to log in to AM/OpenAM using a login URL that references the authentication chain that includes the SAML2 module. For example: 
    http://sp.example.com:8080/openam/XUI/#login/&service=mySAMLChain

See Also

How do I configure the SAML2 Authentication module for Local Account Linking in AM (All versions) and OpenAM 13.x?

FAQ: SAML federation in AM/OpenAM

SAML Federation in AM/OpenAM

Authentication and Single Sign-On Guide › Implementing Authentication › SAML2 Authentication Module

Related Training

N/A

Related Issue Tracker IDs

OPENAM-8071 (Documentation on SAML2 Authn module: add a reference for the need to modify the SP Assertion Consumer Service endpoints)


How do I configure the SAML2 Authentication module for Auto Federation in AM (All versions) and OpenAM 13.x?

The purpose of this article is to provide a quick video tutorial on how to configure the SAML2 Authentication module for auto-federation in AM/OpenAM. This demonstration walks through configuring the module from first principles, showing how to configure a service provider (SP), an identity provider (IdP) and then the Authentication module as part of a login chain.

Configuring the SAML2 Authentication module for auto-federation

Note

This video demonstration uses OpenAM 13.0; although the appearance has changed between AM and OpenAM 13.x, the principles and processes are still applicable. In AM, the options under Federation are now under Realms > [Realm Name] > Applications > SAML.

This video demonstration was recorded in HD and is best viewed in Full Screen mode:

Contributed by David Luna

Video Transcript

Click here to download a transcript of this video tutorial. 

See Also

ohnomorejuzzoblogs - Example Configuration - Dynamic Account Federation

How do I configure the SAML2 Authentication module for Local Account Linking in AM (All versions) and OpenAM 13.x?

How do I set up the SAML2 Authentication module using Integrated Mode in AM (All versions) and OpenAM 13.x?

How do I export and import SAML metadata in AM/OpenAM (All versions)?

FAQ: SAML federation in AM/OpenAM

SAML Federation in AM/OpenAM

Authentication and Single Sign-On Guide › Implementing Authentication › Federation Authentication Module

Reference › Service Endpoints › SAML2 JSP Endpoints

SAML v2.0 Guide › Implementing SAML v2.0 Using the AM Console › To Share Identity and Service Provider Metadata

Related Training

N/A

Related Issue Tracker IDs

OPENAM-8071 (Documentation on SAML2 Authn module: add a reference for the need to modify the SP Assertion Consumer Service endpoints)


How do I create persistent SAML federation between two AM/OpenAM servers where user attributes match?

The purpose of this article is to demonstrate how to create persistent SAML federation between two AM/OpenAM servers in order to create federated Single Sign On (SSO) for accessing protected web content. It assumes you have set up two AM/OpenAM servers, the user attributes used for searching match, you have at least two users created that exist on both servers and you have a policy agent installed that protects your SP server. This example uses SP initiated SSO.

Introduction

By default, to establish persistent federation AM/OpenAM writes two attributes to the users entry in each repository: sun-fm-saml2-nameid-infokey and sun-fm-saml2-nameid-info. The sun-fm-saml2-nameid-infokey contains a unique Identifier used to link the two accounts, by default this a randomly generated key that is common between the IdP and SP. After the initial Federation link is established, only a single login (on the IdP) will be required. These Sunkey values used to store federation linking information require write access to the IdP's user data store.

Note

In situations where one or both of the user data stores are read-only and/or no schema modifications are allowed, you can also achieve persistent federation using transient federation if required. In contrast to persistent federation, transient federation has no user mapping. All users authenticated by an IdP map to a single pre-determined or anonymous user account on the SP; this option is less common as most SPs will want to know the identity of users accessing their systems. Transient federation uses nameid-format:transient instead of nameid-format:unspecified. This article gives you both the persistent federation option and the transient federation option at the relevant points in the procedure for you to pick the required one to use.

In the example procedure in this article, we link two accounts that share unique identifiers, where the unique identifier is the naming attribute used to find the users account, for example, uid or cn. Having the same unique identifier is simpler as it does not require you to map these attributes. 

See How do I create a persistent SAML federation between two AM/OpenAM servers where user attributes are different (and need mapping)? for further information about creating persistent SAML federation if you do need to map these attributes.

Assumptions

Your URLs must be Fully Qualified Domain Names (FQDN), where one URL is for the SP and one is for the IdP.

The steps provided for creating a persistent federation use the following example URLs:

  • IdP - http://idp.acme.com:8080/openam 
  • SP - http://sp.example.com:8080/openam

Additionally, this example procedure assumes the following is true:

  • A Policy Agent is installed that protects your SP server (for example, http://sp.example.com:8080/openam).
  • Two Users have been created that exist on both servers; the steps provided for creating a persistent federation refer to example users: user1 and user2.
  • Both IdP and SP have AM/OpenAM schema. (See Transient option if data stores are read-only and/or no schema modifications are allowed).

Create a hosted IdP and Circle of Trust on the IdP

Note

The Signing Key has been left blank in this example, but you could use the built-in AM/OpenAM test key.

  1. Log into the console for the IdP:
    • AM / OpenAM 13.x console: navigate to Realms > [Realm Name] > Common Tasks > Configure SAMLv2 Provider > Create Hosted Identity Provider > New Circle of Trust and enter a name for the new circle of trust (COT), for example, COT1.
    • Pre-OpenAM 13 console: navigate to Common Tasks > Create Hosted Identity Provider > New Circle of Trust and enter a name for the new circle of trust (COT), for example, COT1.
  2. Click Configure to save your changes.
  3. Click the register a service provider link under the Register a Remote Service Provider section. You will need to return to this page once you have created the hosted SP provider.

Create a hosted SP and Circle of Trust on the SP

  1. Log into the console for the SP:
    • AM / OpenAM 13.x console: navigate to Realms > [Realm Name] > Common Tasks > Configure SAMLv2 Provider > Create Hosted Service Provider > New Circle of Trust and enter the name of the COT you created for the IdP, for example, COT1.
    • Pre-OpenAM 13 console: navigate to Common Tasks > Create Hosted Service Provider > New Circle of Trust and enter the name of the COT you created for the IdP, for example, COT1.
  2. Click Configure to save your changes.
  3. Click Yes when prompted to create a remote identity provider.
  4. Enter the following URL to indicate where the IdP metadata is located: 
    http://idp.acme.com:8080/openam/saml2/jsp/exportmetadata.jsp?entityid=http://idp.acme.com:8080/openam&realm=/
    
  5. Click Configure to save your changes.
  6. Click OK when prompted that the identity provider has been configured.

Create a remote SP on the IdP

  1. Return to the console for the IdP.
  2. Enter the following URL to indicate where the SP metadata is located:
    http://sp.example.com:8080/openam/saml2/jsp/exportmetadata.jsp?entityid=http://sp.example.com:8080/openam&realm=/
  3. Click Configure to save your changes.
  4. Click OK when prompted that the service provider has been configured.

Verifying COTs and providers

  1. Navigate as follows in both consoles and compare details:
    • AM 6 and later console: navigate to Realms > [Realm Name] > Applications > Federation
    • AM 5.x console: navigate to Realms > [Realm Name] > Applications > SAML
    • Pre-AM 5 console: navigate to Federation
    Both AM/OpenAM servers should have the same COT and entity providers that reference each other. Your Circle of Trust Configuration should look similar to this.

Testing federation

Note

Once federation has been established, you will only need to log in once (through the IdP) in future.

  1. Clear your browser cookies and enter the following SSO URL to log in:
    http://sp.example.com:8080/openam/saml2/jsp/spSSOInit.jsp?metaAlias=/sp&idpEntityID=http://idp.acme.com:8080/openam
     The browser will redirect to http://idp.acme.com:8080/openam
  2. Log in with user1. The browser will redirect back to http://sp.example.com:8080/openam
  3. Log in with user1. Federation is now established between your IdP and SP. The SP will confirm SSO by displaying the message “Single Sign-on succeeded.” After the initial Federation link is established, only a single login (on the IdP) will be required.
  4. Enter one of the following Single Logout (SLO) URL's to log out: 
    http://sp.example.com:8080/openam/saml2/jsp/spSingleLogoutInit.jsp?metaAlias=/sp&idpEntityID=http://idp.acme.com:8080/openam
    or 
    http://sp.example.com:8080/openam/SPSloInit?metaAlias=/sp&idpEntityID=http://idp.acme.com:8080/openam
  5. The SP will confirm SLO by displaying the message “SP initiated single logout succeeded.”

Modifying the IdP to prevent sunkey values being used

  1. Return to the console for the IdP:
    • AM 6 and later console: navigate to Realms > [Realm Name] > Applications > Federation > Entity Providers:
    • AM 5.x console: navigate to Realms > [Realm Name] > Applications > SAML > Circle of Trust Configuration > Entity Providers:
    • Pre-AM 5 console: navigate to Federation > Circle of Trust Configuration > Entity Providers:

  1. Click the name of the entity provider that is of type Remote SP. In my example, this is: http://sp.example.com:8080/openam
  2. Navigate to: Assertion Content > NameID Format and select the Disable Federation persistence if NameID Format is unspecified option.
  3. Click Save to save your changes and Back to return to Federation.
  4. Click the name of the entity provider that is of type Hosted IdP. In my example, this is: http://idp.acme.com:8080/openam
  5. Navigate to: Assertion Content > NameID Format > NameID Value Map and remove the urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified= value. Add one of the following new values: Your NameID Value Map should now look similar to this:
    • Persistent federation - urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified=uid
    • Transient federation - urn:oasis:names:tc:SAML:2.0:nameid-format:transient=uid

  1. Click Save to save your changes.

Modifying the SP to prevent sunkey values being used

  1. Return to the console for the SP:
    • AM 6 and later console: navigate to Realms > [Realm Name] > Applications > Federation > Entity Providers:
    • AM 5.x console: navigate to Realms > [Realm Name] > Applications > SAML > Circle of Trust Configuration > Entity Providers:
    • Pre-AM 5 console: navigate to Federation > Circle of Trust Configuration > Entity Providers.
  2. Click the name of the entity provider that is of type Hosted SP. In this example, this is: http://sp.example.com:8080/openam
  3. Navigate to: Assertion Content > NameID Format and select the Disable Federation persistence if NameID Format is unspecified option.
  4. Remove all values in NameID Value Map apart from one; leave only one of the following values:
    • Persistent federation - urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
    • Transient federation - urn:oasis:names:tc:SAML:2.0:nameid-format:transient
  5. Click Save to save your changes. Your NameID Format should now look similar to this:

  1. Navigate to: Assertion Processing > Account Mapper and select the Use Name ID as User ID option.
  2. Click Save to save your changes.

Testing federation

  1. ​Clear your browser cookies and enter the following SSO URL to log in:
    http://sp.example.com:8080/openam/saml2/jsp/spSSOInit.jsp?metaAlias=/sp&idpEntityID=http://idp.acme.com:8080/openam
    The browser will redirect to http://idp.acme.com:8080/openam 
  2. Log in with user2. The browser will redirect back to http://sp.example.com:8080/openam but log in will not be required this time as federation is already established. The SP will confirm SSO by displaying the message “Single Sign-on succeeded.”
  3. Enter the following SLO URL to log out:
    http://sp.example.com:8080/openam/saml2/jsp/spSingleLogoutInit.jsp?metaAlias=/sp&idpEntityID=http://idp.acme.com:8080/openam
    The SP will confirm SLO by displaying the message “SP initiated single logout succeeded.”

Modifying the Policy Agent to use federation

  1. Log into the console for the SP and navigate to the Realm which holds the Agent Profile:
    • AM 6 and later console: navigate to: Realms > [Realm Name] > Applications > Agents > Web or Java > [Agent ID] > AM Services and modify the AM Login URL value to point to the spSSOInit.jsp of the SP server:
      http://sp.example.com:8080/openam/saml2/jsp/spSSOInit.jsp?metaAlias=/sp&idpEntityID=http://idp.acme.com:8080/openam
    • AM 5.x console: navigate to: Realms > [Realm Name] > Applications > Agents > Web or J2EE > [Agent Name] > OpenAM Services and modify the OpenAM Login URL value to point to the spSSOInit.jsp of the SP server per above example URL.
    • OpenAM 13.x console: navigate to Realms > [Realm Name] > Agents > Web or J2EE > [Agent Name] > OpenAM Services and modify the OpenAM Login URL value to point to the spSSOInit.jsp of the SP server per above example URL.
    • Pre-OpenAM 13 console: navigate to Access Control > [Realm Name] > Agents > Web or J2EE > [Agent Name] > OpenAM Services and modify the OpenAM Login URL value to point to the spSSOInit.jsp of the SP server per above example URL.
  2. Navigate to Logout URL on the same page and modify OpenAM Logout URL value to point to spSingleLogoutInit.jsp
    http://sp.example.com:8080/openam/saml2/jsp/spSingleLogoutInit.jsp?metaAlias=/sp&idpEntityID=http://idp.acme.com:8080/openam

Testing the Policy Agent

  1. Clear your browser cookies and enter the URL that the policy agent is protecting. The browser will redirect to http://idp.acme.com:8080/openam 
  2. Log in with user2. The browser will redirect back to the URL that the policy agent is protecting.
Note

Federation was used to authenticate the user at the IdP and policy evaluation took place on the SP. 

See Also

How do I create a persistent SAML federation between two AM/OpenAM servers where user attributes are different (and need mapping)?

How do I configure IdP or SP initiated Single Sign On in AM/OpenAM (All versions)?

How do I configure IdP or SP initiated Single Logout in AM/OpenAM (All versions)?

How do I redirect to a specific page after a successful IdP or SP initiated login in AM/OpenAM (All versions)?

How do I redirect to a specific page after a successful IdP or SP initiated logout in AM/OpenAM (All versions)?

SAML Federation in AM/OpenAM

SAML v2.0 Guide

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs

OPENAM-1012 (IDP initiated SAML2 SLO error when SP does not have SLO binding)

OPENAM-3005 (Exported IdP entity cannot be imported back via console)

OPENAM-830 (Provider urls are created based on host-header name and not name given)

OPENAM-3470 (The SAML2 nameid should not be persisted if the nameid-format is not persistent)


How do I create a persistent SAML federation between two AM/OpenAM servers where user attributes are different (and need mapping)?

The purpose of this article is to create a persistent SAML federation between two AM/OpenAM servers in order to create federated Single Sign On (SSO) for accessing protected web content. It assumes you have set up two AM/OpenAM servers, the user attributes used for searching are different and therefore require mapping, you have at least two users created that exist on both servers and you have a policy agent installed that protects your SP server. Importantly, you must have write access to the IdP's user data store to be able to save the mapping information.

Introduction

This example uses servers that have different unique identifiers, where the unique identifier is the attribute being used to identify and search for users, for example, uid or mail. Having different unique identifiers requires you to map the attributes used for searching and requires write access to the IdP's user data store. Sunkey values are used to store federation linking information when the two servers have different unique identifiers; by default, the two attributes used for storing this linking information are: sun-fm-saml2-nameid-info and sun-fm-saml2-nameid-infokey.

See How do I create persistent SAML federation between two AM/OpenAM servers where user attributes match? for further information about creating persistent SAML federation when you have servers with matching unique identifiers and/or do not have write access to the IdP's user data store.

Assumptions

Your URLs must be Fully Qualified Domain Names (FQDN), where one URL is for the SP and one is for the IdP.

The steps provided for creating a persistent federation use the following example URLs:

  • IdP - http://idp.acme.com:8080/openam 
  • SP - http://sp.example.com:8080/openam

Additionally, these example steps assume the following is true:

  • A Policy Agent is installed that protects your SP server (for example, http://sp.example.com:8080/openam).
  • Two Users have been created that exist on both servers; the steps provided for creating a persistent federation refer to example users: user1 and user2.
  • Both IdP and SP have AM/OpenAM schema.
  • You have write access to the IdP's user data store to be able to save the mapping information.

Create a hosted IdP and Circle of Trust on the IdP

Note

The Signing Key has been left blank in this example, but you could use the built-in AM/OpenAM test key.

  1. Log in to the console for the IdP:
    • AM / OpenAM 13.x console: navigate to Realms > [Realm Name] > Common Tasks > Configure SAMLv2 Provider > Create Hosted Identity Provider > New Circle of Trust and enter a name for the new circle of trust (COT), for example, COT1.
    • Pre-OpenAM 13 console: navigate to Common Tasks > Create Hosted Identity Provider > New Circle of Trust and enter a name for the new circle of trust (COT), for example, COT1.
  2. Click Configure to save your changes.
  3. Click the register a service provider link under the Register a Remote Service Provider section. You will need to return to this page once you have created the hosted SP provider.

Create a hosted SP and Circle of Trust on the SP

  1. Log in to the console for the SP:
    • AM / OpenAM 13.x console: navigate to Realms > [Realm Name] > Common Tasks > Configure SAMLv2 Provider > Create Hosted Service Provider > New Circle of Trust and enter the name of the COT you created for the IdP, for example, COT1.
    • Pre-OpenAM 13 console: navigate to Common Tasks > Create Hosted Service Provider > New Circle of Trust and enter the name of the COT you created for the IdP, for example, COT1.
  2. Click Configure to save your changes.
  3. Click Yes when prompted to create a remote identity provider.
  4. Enter the following URL to indicate where the IdP metadata is located: 
    http://idp.acme.com:8080/openam/saml2/jsp/exportmetadata.jsp?entityid=http://idp.acme.com:8080/openam&realm=/
    
  5. Click Configure to save your changes.
  6. Click OK when prompted that the identity provider has been configured.

Create a remote SP on the IdP

  1. Return to the console for the IdP.
  2. Enter the following URL to indicate where the SP metadata is located:
    http://sp.example.com:8080/openam/saml2/jsp/exportmetadata.jsp?entityid=http://sp.example.com:8080/openam&realm=/
    
  3. Click Configure to save your changes.
  4. Click OK when prompted that the service provider has been configured.

Verifying COTs and providers

  1. Navigate as follows in both consoles and compare details:
    • AM 6 and later console: navigate to Realms > [Realm Name] > Applications > Federation
    • AM 5.x console: navigate to Realms > [Realm Name] > Applications > SAML
    • Pre-AM 5 console: navigate to Federation
    Both AM/OpenAM servers should have the same COT and entity providers that reference each other. Your Circle of Trust Configuration should look similar to this.

Testing federation

Note

Once federation has been established, you will only need to log in once (through the IdP) in future.

  1. Clear your browser cookies and enter the following SSO URL to log in:
    http://sp.example.com:8080/openam/saml2/jsp/spSSOInit.jsp?metaAlias=/sp&idpEntityID=http%3A%2F%2Fidp.acme.com%3A8080%2Fopenam
     The browser will redirect to http://idp.acme.com:8080/openam
  2. Log in with user1. The browser will redirect back to http://sp.example.com:8080/openam
  3. Log in with user1. Federation is now established between your IdP and SP. The SP will confirm SSO by displaying the message “Single Sign-on succeeded.”
  4. Enter the following Single Logout (SLO) URL to log out:
    http://sp.example.com:8080/openam/SPSloInit?binding=urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST 
    The SP will confirm SLO by displaying the message “SP initiated single logout succeeded.”

Checking user data store on directory servers (Optional)

You can optionally check the user data store on the directory servers for both servers to see the two attributes used for linking the user accounts:

sp.example.com (SP)

Actual Values:

  • sun-fm-saml2-nameid-info: http://sp.example.com:8080/openam|http://idp.acme.com:8080/openam|WyJW0z79g0UCvIbsOGhX8tdXcPEV |http://idp.acme.com:8080/openam|urn:oasis:names:tc:SAML:2.0:nameid-format:persistent|null|http://sp.example.com:8080/openam|SPRole|false
  • sun-fm-saml2-nameid-infokey: http://sp.example.com:8080/openam|http://idp.acme.com:8080/openam|WyJW0z79g0UCvIbsOGhX8tdXcPEV

idp.acme.com (IdP)

Actual Values:

  • sun-fm-saml2-nameid-info: http://idp.acme.com:8080/openam|http://sp.example.com:8080/openam|WyJW0z79g0UCvIbsOGhX8tdXcPEV |http://idp.acme.com:8080/openam|urn:oasis:names:tc:SAML:2.0:nameid-format:persistent|null|http://sp.example.com:8080/openam|IDPRole|false
  • sun-fm-saml2-nameid-infokey: http://idp.acme.com:8080/openam|http://sp.example.com:8080/openam|WyJW0z79g0UCvIbsOGhX8tdXcPEV

The NameID used to link the user from IdP to SP is: WyJW0z79g0UCvIbsOGhX8tdXcPEV

Map attributes on IdP

  1. Return to the console for the IdP:
    • AM 6 and later console: navigate to Realms > [Realm Name] > Applications > Federation > Entity Providers:
    • AM 5.x console: navigate to Realms > [Realm Name] > Applications > SAML > Circle of Trust Configuration > Entity Providers:
    • Pre-AM 5 console: navigate to Federation > Circle of Trust Configuration > Entity Providers:

  1. Click the name of the entity provider that is of type Remote SP. In this example, this is: http://sp.example.com:8080/openam
  2. Navigate to Assertion Processing > Attribute Mapper > Attribute Map and map the IdP user attribute to the SP user attribute. For example, if the attribute on the IdP is EmailAddress and the corresponding attribute on the SP is mail, you would enter EmailAddress=mail:

  1. Click Save to save your changes. 

Enable auto federation on SP

  1. Return to the console for the SP:
    • AM 6 and later console: navigate to Realms > [Realm Name] > Applications > Federation > Entity Providers:
    • AM 5.x console: navigate to Realms > [Realm Name] > Applications > SAML > Circle of Trust Configuration > Entity Providers:
    • Pre-AM 5 console: navigate to Federation > Circle of Trust Configuration > Entity Providers.
  2. Click the name of the entity provider that is of type Hosted SP. In this example, this is: http://sp.example.com:8080/openam
  3. Navigate to: Assertion Processing > Auto Federation and select the Enabled option to enable auto federation.
  4. Enter the SP attribute specified in the previous section in the Attribute field. In this example, this is mail:

  1. Click Save to save your changes. 

Testing federation

  1. ​Clear your browser cookies and enter the following SSO URL to log in:
    http://sp.example.com:8080/openam/saml2/jsp/spSSOInit.jsp?metaAlias=/sp&idpEntityID=http%3A%2F%2Fidp.acme.com%3A8080%2Fopenam
    The browser will redirect to http://idp.acme.com:8080/openam 
  2. Log in with user2. The browser will redirect back to http://sp.example.com:8080/openam but log in will not be required this time as federation is already established. The SP will confirm SSO by displaying the message “Single Sign-on succeeded.”
  3. Enter the following SLO URL to log out:
    http://sp.example.com:8080/openam/SPSloInit?binding=urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST
    The SP will confirm SLO by displaying the message “SP initiated single logout succeeded.”

Modifying the Policy Agent to use federation

  1. Return to the console for the SP:
    • AM 6 and later console: navigate to: Realms > [Realm Name] > Applications > Agents > Web or Java > [Agent ID] > AM Services and modify the AM Login URL value to point to the spSSOInit.jsp of the SP server:
      http://sp.example.com:8080/openam/saml2/jsp/spSSOInit.jsp?metaAlias=/sp&idpEntityID=http%3A%2F%2Fidp.acme.com%3A8080%2Fopenam
    • AM 5.x console: navigate to: Realms > [Realm Name] > Applications > Agents > Web or J2EE > [Agent Name] > OpenAM Services and modify the OpenAM Login URL value to point to the spSSOInit.jsp of the SP server per above example URL.
    • OpenAM 13.x console: navigate to Realms > [Realm Name] > Agents > Web or J2EE > [Agent Name] > OpenAM Services and modify the OpenAM Login URL value to point to the spSSOInit.jsp of the SP server per above example URL.
    • Pre-OpenAM 13 console: navigate to Access Control > [Realm Name] > Agents > Web or J2EE > [Agent Name] > OpenAM Services and modify the OpenAM Login URL value to point to the spSSOInit.jsp of the SP server per above example URL.
  2. Navigate to Logout URL on the same page and modify OpenAM Logout URL value to point to SPSloInit:
    http://sp.example.com:8080/openam/SPSloInit?binding=urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST

Testing the Policy Agent

  1. Clear your browser cookies and enter the URL that the policy agent is protecting. The browser will redirect to http://idp.acme.com:8080/openam 
  2. Log in with user2. The browser will redirect back to the URL that the policy agent is protecting.
Note

Federation was used to authenticate the user at the IdP and policy evaluation took place on the SP. 

See Also

How do I create persistent SAML federation between two AM/OpenAM servers where user attributes match?

FAQ: SAML federation in AM/OpenAM

How do I configure IdP or SP initiated Single Sign On in AM/OpenAM (All versions)?

How do I configure IdP or SP initiated Single Logout in AM/OpenAM (All versions)?

How do I redirect to a specific page after a successful IdP or SP initiated login in AM/OpenAM (All versions)?

How do I redirect to a specific page after a successful IdP or SP initiated logout in AM/OpenAM (All versions)?

SAML Federation in AM/OpenAM

SAML v2.0 Guide

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs

OPENAM-1012 (IDP initiated SAML2 SLO error when SP does not have SLO binding)

OPENAM-3005 (Exported IdP entity cannot be imported back via console)

OPENAM-830 (Provider urls are created based on host-header name and not name given)

OPENAM-3470 (The SAML2 nameid should not be persisted if the nameid-format is not persistent)


How do I configure AM/OpenAM (All versions) to integrate with Microsoft Office 365 using SAML2?

The purpose of this article is to provide information on configuring AM/OpenAM to integrate with Microsoft® Office 365® using SAML2 federation. This article assumes you already have a working AM/OpenAM and Office 365 setup.

Overview

Note

If you want to use WS-Federation instead of SAML2 federation, you should refer to: How do I configure AM (All versions) or OpenAM 13.5.x as an Identity Provider for Microsoft Office 365 and Azure using WS-Federation? for further information. WS-Federation provides support for older products such as Office 2010 and federation in conjunction with Azure®.

When integrating Office 365 (O365) with AM/OpenAM using SAML2 federation, O365 acts as the service provider (SP) and AM/OpenAM as the identity provider (IdP).

The expected access flow for O365 in a federated environment is as follows: 

  1. The user navigates to http://login.microsoftonline.com and enters their login name (their password is not required at this stage). Their login name will be in the following format: username@example.com, where the @example.com part tells O365 that this is a federated login. 
  2. O365 looks the user up internally (along with the associated SAML metadata) and starts the SAML flow by redirecting to the AM/OpenAM login page with a SAML AuthN request.
  3. The user enters their AM/OpenAM credentials.
  4. AM/OpenAM authenticates the user and sends a SAML response back to O365. This response includes the required name identifier as well as an attribute called IDPEmail, which is used by O365 to look for the user in its internal repository.
  5. O365 verifies the SAML response, maps the user and then allows the user to SSO.

For the user, it is a simple flow: they will see the O365 login page, the AM/OpenAM login page and finally be logged in to O365. 

Key requirement (persistent NameID)

O365 requires a persistent NameID for federation to work. This means AM/OpenAM must support the following NameID format: urn:oasis:names:tc:SAML:2.0:nameid-format:persistent.

By default, AM/OpenAM writes two attributes to the user's entry in the user repository to establish persistent federation: sun-fm-saml2-nameid-infokey and sun-fm-saml2-nameid-info. The sun-fm-saml2-nameid-infokey contains a unique Identifier used to link the two accounts; by default this is a randomly generated key that is common between the IdP and SP. When a user federates for the first time, they will need to log in to both the IdP and SP to establish the common NameID value. For that reason, the user data store cannot be read-only. After the initial Federation link is established, only a single login (on the IdP) will be required.

Integrating O365 does not follow the rules above. The NameID cannot be generated by the IdP, but instead must be the Azure Active Directory (AD) user's ImmutableID. From the Office 365 SAML 2.0 Federation Implementers Guide:

NameID - The value of this assertion must be the same as the Azure AD user’s ImmutableID. It can be up to 64 alpha numeric characters. Any non HTML safe characters must be encoded, for example a “+” character is shown as “.2B”

To achieve federation, you must pre-populate these SAML attributes. These attributes must be in the following format, where ImmutableID is replaced with an appropriate value:

sun-fm-saml2-nameid-info: http://office365.example.com:8080/openam|urn:federation:MicrosoftOnline|ImmutableID|http://office365.example.com:8080/openam|urn:oasis:names:tc:SAML:2.0:nameid-format:persistent|ImmutableID|urn:federation:MicrosoftOnline|IDPRole|false

sun-fm-saml2-nameid-infokey: http://office365.example.com:8080/openam|urn:federation:MicrosoftOnline|ImmutableID

Where:

  • http://office365.example.com:8080/openam is the IdP entity provider.
  • urn:federation:MicrosoftOnline is the SP entity provider.
Note

These changes must be made directly in your directory server.

As of OpenAM 13.5, it is possible to configure federation with O365 without needing write access to your user store. This means you can configure federation where persistent NameID is required (urn:oasis:names:tc:SAML:2.0:nameid-format:persistent), without writing these user attributes to the user profile. You should ensure you use a linkage attribute that is visible to both AM/OpenAM and O365, such as uid or objectGUID. See OpenAM 13.5 Release Notes › Changes and Deprecated Functionality › Important Changes to Existing Functionality (SAML 2.0 NameID Persistence Extended) for further information.

Different user attributes / user store

If you use a different user store, for example AD, and/or you use attributes other than sun-fm-saml2-nameid-infokey and sun-fm-saml2-nameid-info for persistent federation, you must make the following changes:

  1. Ensure the attributes you want to use exist in the schema for the applicable user store.
  2. Add the attributes you want to use to the data store configuration: 
    • AM 6 and later console: navigate to: Realms > [Realm Name] > Data Stores > [Data Store Name] > User Configuration and add the attributes to the LDAP User Attributes list.
    • AM 5.x / OpenAM 13.x console: navigate to: Realms > [Realm Name] > Data Stores > [Data Store Name] and add the attributes to the LDAP User Attributes list.
    • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Data Stores > [Data Store Name] and add the attributes to the LDAP User Attributes list.
  3. Specify the name of the attributes you are using for persistent federation:
    • AM / OpenAM 13.5 console: navigate to: Configure > Global Services > SAMLv2 Service Configuration and enter the names of the actual attributes being used in the Attribute name for Name ID information and Attribute name for Name ID information key fields. 
    • Pre-OpenAM 13.5 console: navigate to: Configuration > Global > SAMLv2 Service Configuration and enter the names of the actual attributes being used in the Attribute name for Name ID information and Attribute name for Name ID information key fields.
Caution

These changes are global, so will affect all federation setups.

Configuring AM/OpenAM

Caution

Before you start integrating, you must ensure that the same users exist in both O365 and AM/OpenAM for this federation to work.

This example process assumes the following:

  • You are using DS/OpenDJ for your user store.
  • The AM/OpenAM server (IdP) has the AM/OpenAM schema installed.
  • You are using the default sun-fm-saml2-nameid-infokey and sun-fm-saml2-nameid-info attributes.
  • The URL for the IdP is http://office365.example.com:8080/openam - this is also used as the name of the IdP entity provider.
  • The SP entity provider is called urn:federation:MicrosoftOnline (this is the default).

You can configure AM/OpenAM for integration with O365 as follows:

  1. Download the federationmetadata.xml file from O365 and prepare it for import. You do this by removing the content contained within the first set of <signature>...</signature> tags (and the tags themselves) as this section is not compliant and will cause the upload to fail if left in. 
  2. Log into the console for the IdP:
    • AM / OpenAM 13.x console: navigate to Realms > [Realm Name] > Common Tasks > Configure SAMLv2 Provider > Create Hosted Identity Provider, select a signing key to use and enter a name for the new circle of trust (COT), for example, O365.
    • Pre-OpenAM 13 console: navigate to Common Tasks > Create Hosted Identity Provider, select a signing key to use and enter a name for the new circle of trust (COT), for example, O365.
  3. Click the register a service provider link under the Register a Remote Service Provider section.
  4. Select the File option to indicate where the metadata resides and upload the modified federationmetadata.xml file. This should create the SP in the same COT;  your COT and entity providers setup should now look like this:

  1. Select the remote SP entity provider:
    • AM 6 and later console: navigate to: Realms > [Realm Name] > Applications > Federation > Entity Providers and click the name of the Remote SP entity provider
    • AM 5.x console: navigate to: Realms > [Realm Name] > Applications > SAML > Circle of Trust Configuration > Entity Providers and click the name of the Remote SP entity provider (urn:federation:MicrosoftOnline in this example).
    • Pre-AM 5 console: navigate to: Federation > Circle of Trust Configuration > Entity Providers and click the name of the Remote SP entity provider (urn:federation:MicrosoftOnline in this example).
  2. Click the Assertion Processing tab and add a new IDPEmail=mail value to the Attribute Map.
  3. Update your user entries to include the correctly populated sun-fm-saml2-nameid-infokey and sun-fm-saml2-nameid-info attributes. You can do this manually for a single user for testing purposes. For pre-populating all your other users, you could use the ssoadm do-bulk-federation command as detailed in SAML v2.0 Guide › Implementing SAML v2.0 Using the AM Console › Linking Federated Accounts in Bulk.
  4. Export the IdP metadata as described in How do I export and import SAML metadata in AM/OpenAM (All versions)? and give this to the O365 administrator so they can import it into the SP to complete the setup.

Testing federation

To test your federation setup, you can attempt to log in per the flow detailed in the Overview section at the start of this article: 

  1. Navigate to http://login.microsoftonline.com and enter your user name in the format username@example.com (no password is required at this stage).
  2. You should then be redirected to AM/OpenAM where you can log in with your AM/OpenAM credentials.
  3. If successful, you should then be logged into O365 automatically.

Troubleshooting

The following table shows some common errors you may see in the Federation debug log on the AM/OpenAM side and their meanings:

Error Meaning
<samlp:StatusMessage xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"> Creation of NameID is not allowed per AuthnRequest. </samlp:StatusMessage>

This means the user is not correctly pre-provisioned in AM/OpenAM.

You must pre-populate the sun-fm-saml2-nameid-infokey and sun-fm-saml2-nameid-info attributes (or equivalents) with the correct information. See the Key requirement (persistent NameID) section for further information.

ERROR: IDPSSOFederate.doSSOFederate: Unable to do sso or federation.com.sun.identity.saml2.common.SAML2Exception: Identity provider does not support name identifier format urn:oasis:names:tc:SAML:2.0:nameid-format:persistent.

This means the AM/OpenAM configuration has been changed to remove support for the urn:oasis:names:tc:SAML:2.0:nameid-format:persistent NameID format (it is supported by default). 

You need to ensure the AM/OpenAM instance being used as the IdP has urn:oasis:names:tc:SAML:2.0:nameid-format:persistent listed as a supported NameID format:

  • AM 5 and later console: navigate to Realms > [Realm Name] > Applications > SAML > Circle of Trust Configuration > Entity Providers > [IdP Name] > Assertion Content > NameID Format and add urn:oasis:names:tc:SAML:2.0:nameid-format:persistent to the NameID Format List.
  • Pre-AM 5 console: navigate to Federation > Circle of Trust Configuration > Entity Providers > [IdP Name] > Assertion Content > NameID Format and add urn:oasis:names:tc:SAML:2.0:nameid-format:persistent to the NameID Format List.

It is also worth exporting your metadata (standard and extended) to check if a configuration issue is contributing to your issues. You can export this as described in How do I export and import SAML metadata in AM/OpenAM (All versions)? Additionally, you should capture a SAML trace while reproducing the issue. You should follow this process:

  • Start a SAML trace in your browser. There are free third-party tools you can use, for example, in Firefox®, you can use SAML Tracer.
  • Reproduce the issue using your browser.
  • Stop the SAML trace.

On the O365 side, you can try using the Remote Connectivity Analyzer tool to troubleshoot any issues you are experiencing.

See Also

How do I configure AM (All versions) or OpenAM 13.5.x as an Identity Provider for Microsoft Office 365 and Azure using WS-Federation?

How do I export and import SAML metadata in AM/OpenAM (All versions)?

How do I create persistent SAML federation between two AM/OpenAM servers where user attributes match?

FAQ: SAML federation in AM/OpenAM

SAML Federation in AM/OpenAM

SAML v2.0 Guide

Office 365 SAML 2.0 Federation Implementers Guide

OpenAM as an identity provider for Office 365 (WSFed)

OpenAM / Office365 SSO

Related Training

N/A

Related Issue Tracker IDs

OPENAM-8578 (The default WS-Fed and SAML2 IDP attribute mapper should provide a way to Base64 binary encoding of NameID)

OPENAM-8580 (OpenAM should allow to use objectGUID value from AD when working with persistent NameID)

OPENAM-7428 (OpenAM IdP should support SOAP 1.2 when using the SAML ECP profile)

OPENAM-3470 (The SAML2 nameid should not be persisted if the nameid-format is not persistent)

OPENAM-3095 (When a SP sends an unsigned Authn Request using SAML ECP OpenAM sees it as a wrong message)


How do I configure AM (All versions) or OpenAM 13.5.x as an Identity Provider for Microsoft Office 365 and Azure using WS-Federation?

The purpose of this article is to provide information on configuring AM/OpenAM as an Identity Provider (IdP) for Microsoft® Office 365® and Azure® using WS-Federation.

Introduction

This article details the officially supported method for setting up AM/OpenAM to be an IdP for Azure and/or Office 365 (O365). This uses the WS-Federation standard to achieve federation as Microsoft no longer certify third-party IdPs using SAML2 in conjunction with their cloud platform. Although WS-Federation is not as widely used as SAML2, it has the added benefit of supporting much older Office rich clients, such as Office 2010, Office 2011 (Mac® OS X®) as well as third-party mail and calendar clients.

Known issues - AM 5.x and OpenAM 13.5.x

The following known issues exist in AM 5.x and OpenAM 13.5.x:

Known issues - OpenAM 13.5.x

The information in this article will work in OpenAM 13.5.x, but there are known issues as follows:

It is recommended that you use AM 5 or later to integrate with Microsoft Office 365 and Azure, which includes fixes for these issues.

Authentication scenarios

The authentication scenarios available are dependent on the client application and the features that are enabled in O365 and AM/OpenAM. All of the authentication features of AM/OpenAM are supported when the client can support authentication through a web browser, WsFederation Passive Flow:

  • Sign on through a web browser (for example to access SharePoint® online) allows the user to authenticate with all the supported authentication methods in AM/OpenAM, such as Windows Desktop SSO (Integrated Windows Authentication), push authentication and multi factor authentication (MFA).
  • As Word, Excel and PowerPoint 2013 (Windows) and 2016 (Windows and Mac OS) authenticate through a web browser, these also support all of the authentication methods available in AM/OpenAM.    
  • Outlook® 2016 and Skype for business 2016 support web browser authentication (passive flow) when modern authentication is enabled in O365. Once enabled, these applications can support all of the authentication methods available in AM/OpenAM.
  • Older Office applications such as Outlook 2010 (Windows) and Outlook 2011 (Mac OS) only support username/password authentication using WsFederation Active Profile. For this to work correctly, the default chain in the realm must only prompt for a username and password. The procedure below describes a workaround that can allow a chain with MFA or WDSSO to be used for passive flow scenarios, while still having a default chain in a realm that only uses username/password for Outlook 2010/2011. 
  • The Android Native Mail client and the Mac Office 365 client only support the WsFederation Active Profile flow, which requires UPN (User Principal Name) instead of a mapped user name. The syntax for UPN is username@domain. 

The following table illustrates this in more detail:

Office 365 Authentication Scenarios
  WsFed Passive Profile WsFed Passive Profile with Skype and Exchange modern authentication turned on WsFed Passive Profile with Skype and Exchange modern authentication turned on, WsFed Active Profile turned on in AM/OpenAM
Single sign on to Azure and Office 365 web services, such as Sharepoint WDSSO, MFA and username/password WDSSO, MFA and username/password

WDSSO, MFA and username/password

Word, Excel, PowerPoint, OneNote, OneDrive 2016 (Mac OS/Windows) WDSSO, MFA and username/password WDSSO, MFA and username/password

WDSSO, MFA and username/password

Skype for business 2016 and Outlook 2016

N/A

WDSSO, MFA and username/password

WDSSO, MFA and username/password

Word, Excel, PowerPoint, OneNote, OneDrive 2013 (Windows) WDSSO, MFA and username/password WDSSO, MFA and username/password

WDSSO, MFA and username/password

Outlook and Lync 2013 (Windows)

N/A

N/A

username and password

Microsoft Office365 IOS/Android apps username and password username and password

username and password

Outook 2011 (Mac) and Outlook 2010 (WIndows) N/A

N/A

username and password

Lync 2011 (Mac), Lync 2010 (Windows)

N/A

N/A

username and password

Third-party & native mail, calendar, notes and tasks apps

N/A

N/A

username and password

Prerequisites

  1. A business O365 subscription or Azure subscription, capable of federating with third-party IdPs.
  2. A public DNS zone which has been configured with the DNS records required for use with O365/Azure.
  3. An AM 5 or later / OpenAM 13.5.x deployment running on SSL. See Installation GuideDevelopment GuideHow do I enable SSL in AM/OpenAM (All versions) post-install? and How do I enable SSL in AM/OpenAM (All versions) for an existing installation? for further information.
  4. If you require authentication from mail clients or messaging clients like Skype for business or Lync, then your AM/OpenAM deployment must be available publicly on the internet, protected by a publicly trusted SSL certificate.
  5. Users in a directory service such as DS/OpenDJ or Active Directory (AD), provisioned with:
    • A unique identifier such as employeeNumber or ObjectGUID.
    • A unique email address style identifier, such as an email address in the mail attribute, or userPrincipalName. The domain in this identifier must match the domain that is set up in your O365/Azure subscription.
  6. A data store configured in a given realm in AM/OpenAM that has been configured to load profiles from your directory service. See Setup and Maintenance Guide › Setting Up Identity Data Stores and How do I create a user data store in AM/OpenAM (All versions) using ssoadm? for further information.
  7. An LDAP or AD authentication module that has been configured to authenticate users against your directory service. This module should be part of the chain that is set as the organizational chain to use in the realm. See Authentication and Single Sign-On Guide › Configuring Authentication Modules for further information.
  8. Accounts provisioned in Azure AD/O365 with attributes matching the accounts in your directory service. For example:
    • For a DS/OpenDJ data store:
      • The mail attribute on a DS/OpenDJ user could map to the userPrincripalName attribute on the equivalent O365/Azure user.
      • The employeeNumber on a DS/OpenDJ user could map to the ImmutableID attribute on the equivalent O365/Azure user.
    • For an AD data store (or an environment where you have, or are migrating from DirSync or ADFS):
      • The userPrincipalName on an AD user could could map to the userPrincripalName attribute on the equivalent O365/Azure user.
      • The ObjectGUID on an AD user, converted to base64 (that is, ObjectGUID;binary), could map to the ImmutableID attribute on the equivalent O365/Azure user.
  9. A client machine with Java® installed to run the metadata generation tool.
  10. A Windows VM (Windows 8.1 onwards) to configure O365 using PowerShell if you are responsible for the configuration.
  11. A token signing certificate, installed in AM/OpenAM, for signing the assertion that is sent to O365/Azure.
  12. If you plan to use Windows Desktop SSO (WDSSO, also known as Integrated Windows Authentication or Kerberos), you will need a WDSSO module configured in your realm with appropriate keytab files configured. See How do I set up Windows Desktop SSO in AM/OpenAM (All versions)? and How do I set up the WDSSO authentication module in AM/OpenAM (All versions) in a load balanced environment? for further information.

Configuring AM/OpenAM

You can configure AM/OpenAM as follows: 

  1. In your LDAP or AD authentication module, locate the Attribute Used to Search for a User to Be Authenticated. If you haven't done so already, add the attribute containing your email address style identifier here, so that a user can logon with this identifier (this is typically mail or userPrincipalName):
    • Console: navigate to: Realms > [Realm Name] > Authentication > Modules > [Module Name] > Attributes Used to Search for a User to be Authenticated and add the attribute.

  1. Add your AD or LDAP module to a chain that is the organizational default chain in the realm by navigating to: Realms > [Realm Name] > Authentication > Chains > [Chain Name] and add your module.
  2. Test that a user can now authenticate with your email address style identifier identifier.
  3. If you are using WDSSO, navigate to: Realms > [Realm Name] > Authentication > Chains > [Chain Name] and add your WDSSO module to another chain as SUFFICIENT, followed by your AD or LDAP module as REQUIRED. For example, if you are using the LDAP module:
    WDSSO    -> SUFFICIENT
    LDAP     -> REQUIRED
  4. If a circle of trust does not exist for your realm, navigate to the Federation configuration page in AM/OpenAM and create a circle of trust:
    • AM 6 and later console: navigate to Realms > [Realm Name] > Applications > Federation, click Add Circle of Trust and enter details for your new COT.
    • AM 5.x console: navigate to Realms > [Realm Name] > Applications > SAML > Circle of Trust, click New and enter details for your new COT.
    • OpenAM 13.5.x console: navigate to: Federation > Circle of Trust, click New and enter details for your new COT.
  5. Download and run the O365 Metadata generation tool from the Bitbucket® Server. This tool generates the necessary metadata to create a pre-configured WS-Federation IdP and SP entry for O365/Azure.
  6. Follow the prompts in the tool:
    • domain This is the DNS domain that has been configured in O365/Azure and should match the domain of the email address style identifier on your user accounts.
    • realm name The path to the realm when your users are authenticating in AM/OpenAM. The top level realm is /, a realm called "myrealm" is /myrealm, a subrealm of that realm would be /myrealm/mysubrealm.
    • OpenAM service URL The https URL of AM/OpenAM that your users use to reach AM/OpenAM (usually your load balancer URL), for example https://idp.example.com:8443/openam
    • name of circle of trust The name of the circle of trust that you configured in step 5.
    • choose a URI name for your OpenAM IDP This is the unique identifier of your IdP in O365/Azure. This can be anything you want, but to ensure it is unique, it is typically set to the same value as the OpenAM service URL. Just use the default value if you don't already have an IdP configured.
    • choose a meta alias for your IDP A metaAlias is a means of uniquely identifying a given entity provider within AM/OpenAM by using an alias that is suffixed to each AM/OpenAM endpoint. Use the default value if you don't know what to do here.
    • name of signing certificate in OpenAM The alias of your token signing certificate in AM/OpenAM's truststore. It is possible to use the test certificate, but this is not recommended. Using the test certificate here will allow anyone to impersonate AM/OpenAM and gain access to your O365/Azure subscription.
    • name of attribute to map to UPN The attribute that holds the email address style identifier in your AM/OpenAM data store. This attribute will map to the userPrincipalName attribute of your user accounts in O365/Azure.
    • name of attribute to map to ImmutableID The attribute that holds a unique identifier, such as employeenumber or objectGUID.
    • Do you wish to define an Authentication URL If you are using a chain with more than one module (or WDSSO and/or MFA) and you need to support older clients such as Outlook 2010/2011, set the authentication URL to the following:
      https://<OpenAM service URL>/UI/Login?service=<wdssoChainName> 
      where <OpenAM service URL> is the URL you defined earlier in the tool, and wdssoChainName is the chain containing your Windows Desktop SSO module that you created in step 4.
    • enter file name prefix This is a prefix which you can optionally give to the files that the tool generates.

  1. Import the metadata and extended metadata for your IdP. These files end with the names o365-idp-metadata.xml and o365-idp-metadata-extended.xml respectively. Make sure you select the correct realm when importing the files. See How do I export and import SAML metadata in AM/OpenAM (All versions)? for further information.
  2. Import the metadata and extended metadata for your SP (files ending in o365-sp-metadata.xml and o365-sp-metadata-extended.xml), ensuring you select the correct realm. See How do I export and import SAML metadata in AM/OpenAM (All versions)? for further information. For example, your configuration would now look similar to:

  1. Obtain the base64 encoded x.509 public certificate of your token signing key. Remove any line breaks from the encoded certificate and paste it into the PowerShell script that the tool generated (ends in o365-powershell-cfg.ps1) between the double quotes on the line saying $SigningCert = "X", replacing the X character. The value to paste here can be obtained by examining the AM/OpenAM metadata located in the URL displayed at the end of the tool, or by running keytool like so (depending on your keystore format):
    • JCEKS format:
      $ keytool -list -rfc  -keystore /path-to-openam-config/keystore.jceks -storetype JCEKS -alias <certificate alias name>
    • JKS format:
      $ keytool -list -rfc  -keystore /path-to-openam-config/keystore.jks -alias <certificate alias name>

Configuring O365/Azure

The remainder of the configuration steps are carried out in the O365/Azure PowerShell management console. This may be handled by someone else in your organization. If that is the case, it would be appropriate to provide that person with the PowerShell script that was generated by the tool (which you altered to include your token signing certificate) and the steps below:

  1. Connect to O365/Azure on a Windows machine that has been set up for administering Azure with PowerShell. Instructions for setting up a machine like this are located in the comments at the top of the PowerShell script that was generated by the tool in the previous section.
  2. Execute the script generated by the tool once connected. Note that it can take some time for the settings in O365/Azure to take effect. Users should now be able to access O365/Azure web-based services (such as SharePoint online) by signing on at https://login.microsoftonline.com
  3. Use your PowerShell console to enable modern authentication in the Skype for business and Exchange online tenants:

Limitations

You should be aware of the following limitations:

  • WS-Federation Active Requestor profile (the mode that is used by Outlook 2010/2011 to retrieve mail) only supports authentication using the default chain in the realm, and only supports username and password authentication. A default chain in the realm with other modules present will cause authentication via Active Requestor profile to fail.
  • Active Requestor profile fails in a sub-realm when used in combination with OpenAM 13.5.x due to OPENAM-9425 (WS-Federation active profile fails in subrealm). A patch is available to ForgeRock customers to correct this issue.
  • The approach used to support WDSSO (Integrated Windows Authentication) enables this form of authentication when IdP or SP initiated SSO is used in combination with the O365/SP only. It does not generally enable WDSSO for authentication in the realm, as this would prevent Active Requestor profile authentication from working correctly.

SSO URLs

SP initiated SSO

SP initiated SSO can be achieved by visiting the following URL on O365/Azure. The username in the URL parameter does not have to exist, but the domain suffix needs to be accurate for redirection to occur correctly:

https://login.microsoftonline.com/?username=anon@yourdomain.com

IdP initiated SSO

IdP initiated SSO can be achieved using a URL like the following for the top level realm and an IdP with the metaAlias "wsidp":

https://host1.idp.example.com:8443/openam/WSFederationServlet/metaAlias/wsidp?wa=wsignin1.0&wtrealm=urn%3afederation%3aMicrosoftOnline

 Another IdP initiated SSO example, for a realm called mySubRealm, which is a sub realm of myRealm, and an IdP with the metaAlias "myidp":

https://host1.idp.example.com:8443/openam/WSFederationServlet/metaAlias/myRealm/mySubRealm/myidp?wa=wsignin1.0&wtrealm=urn%3afederation%3aMicrosoftOnline

See Also

What federation standards does AM/OpenAM support?

How do I configure AM/OpenAM (All versions) to integrate with Microsoft Office 365 using SAML2?

Configuring and troubleshooting WDSSO in AM/OpenAM

OpenAM as an identity provider for Office 365 (WSFed)

Related Training

N/A

Related Issue Tracker IDs

OPENAM-12261 (Honor org.apache.xml.security.ignoreLineBreaks=true when generating WS-Fed Assertions)

OPENAM-12161 (Expires attribute in WS-Fed Active Requestor Profile is expected but is optional)

OPENAM-9425 (WS-Federation active profile fails in subrealm)

OPENAM-9301 (WS-Federation Active Requestor Profile can fail with NPE if authentication was not successful)

OPENAM-9300 (WS-Federation Active Requestor Profile metadata uses incorrect targetNamespace)

OPENAM-9295 (WS-Federation IDP NameID attribute does not display binary attribute)

OPENAM-9293 (Authenticator class needs to be filled in for WSFED active requestor profile)


How do I set up an IdP Proxy environment in AM/OpenAM (All versions)?

The purpose of this article is to provide a quick step-by-step guide to configure a test environment in AM/OpenAM consisting of a SAML2 Service Provider (SP), SAML2 IdP Proxy and a SAML2 Identity Provider (IdP).

Overview

The following steps are used to set up an IdP Proxy environment; the subsequent sections provide more detail:

  1. Configure the SP instance:
    1. Create the hosted SP.
    2. Configure the SP to allow its requests to be proxied; this is not allowed by default.
    3. Configure the remote IdP proxy (proxy with the role of IdP).
  2. Configure the IdP instance:
    1. Create the hosted IdP.
    2. Configure the remote proxy (proxy with the role of SP).
  3. Configure the proxy instance:
    1. Create the hosted IdP proxy.
    2. Configure the remote IdP.
    3. Configure the remote SP.
    4. Configure the Proxy section of the remote SP.

Prerequisites

You will need to install three AM/OpenAM instances on three different domains. In this article, we are using the following URLs:

  • SP: http://sp.example.com:38080/openam
  • IdP Proxy: http://proxy.example.info:48080/openam
  • IdP: http://idp.example.net:28080/openam

The high level view of how an IdP Proxy works is as follows:

Known issue

There is a known issue with the IDPFinder functionality in AM 5, AM 5.1, AM 5.1.1 and OpenAM 12.x, 13.0, 13.5: OPENAM-3679 (IDP Finder fails to validate relaystate). This is fixed in AM 5.5 and OpenAM 13.5.1.

The workaround is to remove the relayState validation by commenting out the following section in the proxyidpfinder.jsp file (located in the /path/to/tomcat/webapps/openam directory on the IdP proxy instance):

if (relayState == null || relayState.isEmpty() ||
    !SAML2Utils.isRelayStateURLValid(request, relayState, SAML2Constants.IDP_ROLE)) {
%>
    <jsp:forward page="<%= errorURL %>" />
<%
}

Configuring the SP instance

In this section, we will configure the SP instance:

  1. Create the Circle of Trust (COT) and SP:
    • AM / OpenAM 13.x console: navigate to Realms > [Realm Name] > Common Tasks > Configure SAMLv2 Provider > Create Hosted Service Provider > New Circle of Trust and enter a name for the new COT, for example, SPCot.
    • Pre-OpenAM 13 console: navigate to Common Tasks > Create Hosted Service Provider > New Circle of Trust and enter a name for the new COT, for example, SPCot.
  2. Modify the SP to allow its requests to be proxied: 
    • AM 6 and later console: navigate to Realms > [Realm Name] > Applications > Federation > Entity Providers > [Hosted SP Name] > Advanced > IDP Proxy, select Enabled for IDP Proxy and set the Proxy Count to 2.
    • AM 5.x console: navigate to Realms > [Realm Name] > Applications > SAML > Circle of Trust Configuration > Entity Providers > [Hosted SP Name] > Advanced > IDP Proxy, select Enabled for IDP Proxy and set the Proxy Count to 2. 
    • Pre-AM 5 console: navigate to Federation > Circle of Trust Configuration > Entity Providers > [Hosted SP Name] > Advanced > IDP Proxy, select Enabled for IDP Proxy and set the Proxy Count to 2.
  3. Download the template metadata; KBProxy_remote_proxy_meta_IDP_1350+.xml and update the file to replace the http://proxy.example.info:48080/openam hostname with your own hostname.
Caution

The default test certificate changed in OpenAM 13.5. If you are using a pre-OpenAM 13.5 version, you should modify the <X509Certificate> blocks in the downloaded metadata file accordingly.

  1. Configure the remote IdP proxy (proxy with the role of IdP):
    • AM / OpenAM 13.x console: navigate to Realms > [Realm Name] > Common Tasks > Configure SAMLv2 Provider > Configure Remote Identity Provider, select the updated KBProxy_remote_proxy_meta_IDP_1350+.xml file to upload and select the COT you created in step 1. Click Configure to create the remote IdP proxy.
    • Pre-OpenAM 13 console: navigate to Common Tasks > Configure Remote Identity Provider, select the updated KBProxy_remote_proxy_meta_IDP_1350+.xml file to upload and select the COT you created in step 1. Click Configure to create the remote IdP proxy.
    The resulting federation configuration will look like this:

Configuring the IdP instance

In this section, we will configure the IdP instance:

  1. Create the Circle of Trust (COT) and IdP:
    • AM / OpenAM 13.x console: navigate to Realms > [Realm Name] > Common Tasks > Configure SAMLv2 Provider > Create Hosted Identity Provider > New Circle of Trust and enter a name for the new COT, for example, idpcot.
    • Pre-OpenAM 13 console: navigate to Common Tasks > Create Hosted Identity Provider > New Circle of Trust and enter a name for the new COT, for example, idpcot.
  2. Download the template metadata; KBProxy_remote_proxy_meta_SP_1350+.xml and update the file to replace the http://proxy.example.info:48080/openam hostname with your own hostname.
Caution

The default test certificate changed in OpenAM 13.5. If you are using a pre-OpenAM 13.5 version, you should modify the <X509Certificate> blocks in the downloaded metadata file accordingly.

  1. Configure the remote proxy (proxy with the role of SP):
    • AM / OpenAM 13.x console: navigate to Realms > [Realm Name] > Common Tasks > Configure SAMLv2 Provider > Configure Remote Service Provider, select the updated KBProxy_remote_proxy_meta_SP_1350+.xml file to upload and select the COT you created in step 1. Click Configure to create the remote proxy.
    • Pre-OpenAM 13 console: navigate to Common Tasks > Configure Remote Service Provider, select the updated KBProxy_remote_proxy_meta_SP_1350+.xml file to upload and select the COT you created in step 1. Click Configure to create the remote proxy.
    The resulting federation configuration will look like this:

Configuring the proxy instance

In this section, we will configure the proxy instance:

  1. Download the following template metadata files:
Caution

The default test certificate changed in OpenAM 13.5. If you are using a pre-OpenAM 13.5 version, you should modify the <X509Certificate> blocks in the downloaded metadata files accordingly.

  1. Update the metadata files to replace the http://proxy.example.info:48080/openam hostname with your own hostname.
  2. Create the hosted IdP proxy:
    • AM 6 and later console: navigate to Realms > [Realm Name] > Applications > Federation > Entity Providers > Import Entity and select the KBProxy_hosted_proxy_meta_1350+.xml file to upload for the metadata and the KBProxy_hosted_proxy_extended_1350+.xml file to upload for the extended metadata. Click OK to import the metadata files.
    • AM 5.x console: navigate to Realms > [Realm Name] > Applications > SAML > Circle of Trust Configuration > Entity Providers > Import Entity and select the KBProxy_hosted_proxy_meta_1350+.xml file to upload for the metadata and the KBProxy_hosted_proxy_extended_1350+.xml file to upload for the extended metadata. Click OK to import the metadata files.
    • Pre-AM 5 console: navigate to Federation > Circle of Trust Configuration > Entity Providers > Import Entity and select the KBProxy_hosted_proxy_meta_1350+.xml file to upload for the metadata and the KBProxy_hosted_proxy_extended_1350+.xml file to upload for the extended metadata. Click OK to import the metadata files.
  3. Add the proxy entity to a new COT:
    • AM 6 and later console: navigate to Realms > [Realm Name] > Applications > Federation, click Add Circle of Trust and enter a name for the new COT, for example, proxycot and add the IdP proxy entity to the COT.
    • AM 5.x console: navigate to Realms > [Realm Name] > Applications > SAML > Circle of Trust Configuration > New, enter a name for the new COT, for example, proxycot and add the IdP proxy entity to the COT.
    • Pre-AM 5 console: navigate to Federation > Circle of Trust Configuration > New, enter a name for the new COT, for example, proxycot and add the IdP proxy entity to the COT.
  4. Configure the remote IdP:
    • AM / OpenAM 13.x console: navigate to Realms > [Realm Name] > Common Tasks > Configure SAMLv2 Provider > Configure Remote Identity Provider and enter http://idp.example.net:28080/openam/saml2/jsp/exportmetadata.jsp in the URL where metadata is located field and click Configure.
    • Pre-OpenAM 13 console: navigate to Common Tasks > Configure Remote Identity Provider and enter http://idp.example.net:28080/openam/saml2/jsp/exportmetadata.jsp in the URL where metadata is located field and click Configure.
  5. Configure the remote SP:
    • AM / OpenAM 13.x console: navigate to Realms > [Realm Name] > Common Tasks > Configure SAMLv2 Provider > Configure Remote Service Provider and enter http://sp.example.com:38080/openam/saml2/jsp/exportmetadata.jsp in the URL where metadata is located field and click Configure.
    • Pre-OpenAM 13 console: navigate to Common Tasks > Configure Remote Service Provider and enter http://sp.example.com:38080/openam/saml2/jsp/exportmetadata.jsp in the URL where metadata is located field and click Configure.
  6. Modify the remote SP to allow its requests to be proxied: 
    • AM 6 and later console: navigate to Realms > [Realm Name] > Applications > Federation > Entity Providers > [Remote SP Name] > Advanced > IDP Proxy and make the following changes:
      • Select Enabled for IDP Proxy.
      • Set the Proxy Count to 2.
      • Add http://idp.example.net:28080/openam to IDP Proxy List.
    • AM 5.x console: navigate to Realms > [Realm Name] > Applications > SAML > Circle of Trust Configuration > Entity Providers > [Remote SP Name] > Advanced > IDP Proxy and make the same changes as above.
    • Pre-AM 5 console: navigate to Federation > Circle of Trust Configuration > Entity Providers > [Remote SP Name] > Advanced > IDP Proxy and make the same changes as above.
    The resulting federation configuration will look like:

 

Testing the flow

Note

Once federation has been established, you will only need to log in once (through the IdP) in future.

  1. Access the following URL in a browser:
    http://sp.example.com:38080/openam/saml2/jsp/spSSOInit.jsp?metaAlias=/sp&idpEntityID=http://proxy.example.info:48080/openam
  2. Log in as the demo user in the IdP (demo / changeit). The browser will redirect you to the IdP Proxy.
  3. Log in as the demo user in the IdP proxy (demo / changeit). The browser will redirect you to the SP.
  4. Log in as the demo user in the SP to finish linking all the accounts. The message "Single Sign-on succeeded" will be displayed.
  5. Confirm the federation is established by using the URL from step 1 in a different browser. After logging into IdP (step 2), Single Sign-on is achieved.

See Also

How do I use an IdP Proxy with SAML2 federation in AM/OpenAM (All versions)?

FAQ: SAML federation in AM/OpenAM

SAML Federation in AM/OpenAM

SAML v2.0 Guide

Related Training

N/A

Related Issue Tracker IDs

OPENAM-12128 (IdP-Proxy - SP initiated single logout fails in multi-instance deployment with SAML2 failover enabled)

OPENAM-11638 (IdP-Proxy - proxyidpfinder.jsp fails due to failing MetaAlias determination)

OPENAM-11636 (IdP-Proxy - proxyidpfinder.jsp is not triggered when 'Use IDP Finder' is enabled for remote SP entity)

OPENAM-11477 (SLO through IDP Proxy loses the RelayState )

OPENAM-11219 (IDP Proxy and some Auth Modules do not set sticky cookie when Platform cookie is empty)

OPENAM-11210 (IDP Proxy does not set sticky cookie before redirect AuthnRequest to IDP)

OPENAM-10284 (Session Failover does not work correctly in IDP Proxy when authoritative server is down during an attempted logout)

OPENAM-9919 (IDP Proxy fails if Assertion is Encrypted)

OPENAM-5357 (IDPProxy unspecified/persistent with anonymous user)

OPENAM-3679 (IDP Finder fails to validate relaystate)


How do I configure AM/OpenAM (All versions) as an IdP when going through a proxy?

The purpose of this article is to provide information on configuring AM/OpenAM as a hosted IdP when going through a proxy, such as a load balancer. It assumes you have already created the hosted IdP.

Configuring AM/OpenAM

When you create a hosted IdP in AM/OpenAM, the server name is automatically used as the hostname for the IdP. If you go through a proxy or load balancer, you need to update all pre-populated instances of the hostname with the name of your proxy or load balancer.

The following URLs are used in this example:

  • Server name - http://host1.example.com:18080/openam
  • Load balancer name - http://lb.openam.com:8080/openam

You can configure AM/OpenAM as follows:  

  1. Back up AM/OpenAM configuration as described in How do I make a backup of configuration data in AM/OpenAM (All versions)? 
  2. Export the IdP's standard and extended metadata files using the following ssoadm command:
    $ ./ssoadm export-entity -u [adminID] -f [passwordfile] -e [realmname] -y [entityID] -c saml2 -m [metadataXMLfile] -x [extendedXMLfile]
    replacing [adminID], [passwordfile], [realmname], [entityID], [metadataXMLfile] and [extendedXMLfile] with appropriate values.
  3. Update all the Service location URLs in the standard metadata file by replacing the server name part of the URL with the proxy name instead. For example, the ArtifactResolutionService looked like this before the change:
         <ArtifactResolutionService index="0" isDefault="true" Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP" Location="http://host1.example.com:18080/openam/ArtifactResolver/metaAlias/idp"/>
    
    and like this after the change:
         <ArtifactResolutionService index="0" isDefault="true" Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP" Location="http://lb.openam.com:8080/openam/ArtifactResolver/metaAlias/idp"/>
    
  4. Update any URLs (other than the entityID) in the extended metadata file by replacing the server name part of the URL with the proxy name instead. For example, the saeIDPUrl would now look like this after the change:
    <Attribute name="saeIDPUrl">
         <Value>http://lb.openam.com:8080/openam/idpsaehandler/metaAlias/idp</Value> 
    </Attribute>  
    
  5. Remove the hosted IdP configuration from AM/OpenAM before importing the modified metadata files using the following ssoadm command:
    $ ./ssoadm delete-entity -u [adminID] -f [passwordfile] -e [realmname] -y [entityID] -c saml2
    replacing [adminID], [passwordfile], [realmname] and [entityID] with appropriate values.
  6. Import the modified IdP's standard and extended metadata files into AM/OpenAM using the following ssoadm command:
    $ ./ssoadm import-entity -u [adminID] -f [passwordfile] -e [realmname] -t [entityCOT] -c saml2 -m [metadataXMLfile] -x [extendedXMLfile] 
    replacing [adminID], [passwordfile], [realmname], [entityCOT], [metadataXMLfile] and [extendedXMLfile] with appropriate values.

See Also

FAQ: Backing up AM/OpenAM

SAML v2.0 Guide

Reference › Command Line Tools › ssoadm

Setup and Maintenance Guide › Maintaining an Instance › Backing Up and Restoring Configurations

Related Training

N/A

Related Issue Tracker IDs

N/A


How do I use an IdP Proxy with SAML2 federation in AM/OpenAM (All versions)?

The purpose of this article is to provide a video demonstration that will help guide you through understanding and configuring an IdP Proxy with SAML2 federation in AM/OpenAM. An IdP Proxy is essentially an intermediary component between the application (Service Provider) and different Identity Providers, which allows an application to be accessible from multiple identity sources.


How do I create a hosted IdP or SP in AM/OpenAM (All versions) using ssoadm?

The purpose of this article is to provide information on creating a hosted IdP or SP in AM/OpenAM using ssoadm. Using ssoadm allows you to automate the entire entity provider creation process, including adding attribute mapping.

Creating a hosted IdP or SP

You can create a hosted IdP or SP using ssoadm as follows: 

  1. Create the Circle of Trust (COT) unless it already exists:
    $ ./ssoadm create-cot -u [adminID] -f [passwordfile] -e [realmname] -t [entityCOT]
    replacing [adminID], [passwordfile], [realmname], [entityCOT] with appropriate values. You will see the following response if this was successful:
    Circle of trust, [entityCOT] was created.
  2. Create the metadata template XML files unless they already exist:
    $ ./ssoadm create-metadata-templ -u [adminID] -f [passwordfile] -y [entityID] -c saml2 -m [metadataXMLfile] -x [extendedXMLfile] [metaAlias] 
    
    replacing [adminID], [passwordfile], [entityID], [metadataXMLfile], [extendedXMLfile] and [metaAlias] with appropriate values, where [metaAlias] is one of the following options and values depending on the type of entity provider you are creating:
    • IdP - this should be option -i with a value equal to the metaAlias for the hosted identity provider and should be in the format: [realm name]/[metaAlias], for example: -i /idp for a metaAlias of idp in the top level realm.
    • SP - this should be option -s with a value equal to the metaAlias for the hosted service provider and should be in the same format as detailed above for the IdP.
    For example, if you wanted to create metadata template XML files for your IdP (with an ID of EmployeeIdP and a metaAlias of idp in realm employees), your command would look similar to this:
    $ ./ssoadm create-metadata-templ -u amadmin -f pwd.txt -y EmployeeIdP -c saml2 -m standard.xml -x extended.xml -i employees/idp
    You will see the following response if this was successful:
    Hosted entity configuration was written to extended.xml. 
    Hosted entity descriptor was written to standard.xml.
Note

This simple example create-metadata-templ command creates basic template files, which you can use as a start point for your rmetadata files. However, you can create more comprehensive template files, if required, by specifying other properties as detailed in Reference › Command Line Tools › ssoadm create-metadata-templ.

  1. Update your metadata files as necessary and include any additional details needed. If you want to map attributes, you can add attribute mapping to the extended metadata file using the following format:
    <Attribute name="attributeMap">
         <Value>EmailAddress=mail</Value>
         <Value>username=uid</Value>
    </Attribute>
    
    Where the first attribute listed (EmailAddress and username in this example) are the attributes used by the entity provider you are creating.
  2. Import the metadata files to create the entity provider in AM/OpenAM:
    $ ./ssoadm import-entity -u [adminID] -f [passwordfile] -e [realmname] -t [entityCOT] -c saml2 -m [metadataXMLfile] -x [extendedXMLfile]
    replacing [adminID], [passwordfile], [realmname], [entityCOT], [metadataXMLfile] and [extendedXMLfile] with appropriate values. You will see the following response if this was successful:
    Import file, [metadataXMLfile].
    Import file, [extendedXMLfile].
Note

You could script these changes to fully automate updating your entity providers. See How do I make batch changes using ssoadm in AM/OpenAM (All versions)? for further information on scripting ssoadm commands.

See Also

How do I export and import SAML metadata in AM/OpenAM (All versions)?

How do I update metadata for an IdP or SP in AM/OpenAM (All versions) using ssoadm?

How do I change the metaAlias for an existing IdP or SP in AM/OpenAM (All versions)?

SAML Federation in AM/OpenAM

SAML v2.0 Guide

Reference › Command Line Tools › ssoadm

Related Training

N/A

Related Issue Tracker IDs

OPENAM-3172 (ssoadm create-metadata-templ fails with Exception)


How do I register a remote IdP or SP in AM/OpenAM (All versions) using ssoadm?

The purpose of this article is to provide information on registering a remote IdP or SP in AM/OpenAM using ssoadm. Using ssoadm allows you to automate the entire entity provider creation process, including adding attribute mapping.

Registering a remote IdP or SP

You can register a remote IdP or SP using ssoadm as follows: 

  1. Create the Circle of Trust (COT) unless it already exists:
    $ ./ssoadm create-cot -u [adminID] -f [passwordfile] -e [realmname] -t [entityCOT]
    replacing [adminID], [passwordfile], [realmname], [entityCOT] with appropriate values. You will see the following response if this was successful:
    Circle of trust, [entityCOT] was created.
  2. Create the metadata template XML files unless they already exist:
    $ ./ssoadm create-metadata-templ -u [adminID] -f [passwordfile] -y [entityID] -c saml2 -m [metadataXMLfile] -x [extendedXMLfile] [metaAlias] 
    
    replacing [adminID], [passwordfile], [entityID], [metadataXMLfile], [extendedXMLfile] and [metaAlias] with appropriate values, where [metaAlias] is one of the following options and values depending on the type of entity provider you are creating:
    • IdP - this should be option -i with a value equal to the metaAlias for the remote identity provider and should be in the format: [realm name]/[metaAlias].
    • SP - this should be option -s with a value equal to the metaAlias for the remote service provider and should be in the same format as detailed above for the IdP.
    For example, if you wanted to create metadata template XML files for your IdP (with an ID of EmployeeIdP and a metaAlias of idp in realm employees), your command would look similar to this:
    $ ./ssoadm create-metadata-templ -u amadmin -f pwd.txt -y EmployeeIdP -c saml2 -m standard.xml -x extended.xml -i employees/idp
    You will see the following response if this was successful:
    Remote entity configuration was written to extended.xml. 
    Remote entity descriptor was written to standard.xml.
Note

This simple example create-metadata-templ command creates basic template files, which you can use as a start point for your metadata files. However, you can create more comprehensive template files, if required, by specifying other properties as detailed in Reference › Command Line Tools › ssoadm create-metadata-templ.

  1. Update the extended metadata file to indicate it is a remote entity provider you want to create. Change the following hosted="true" value:
    <EntityConfig xmlns="urn:sun:fm:SAML:2.0:entityconfig"
        xmlns:fm="urn:sun:fm:SAML:2.0:entityconfig"
        hosted="true"
    
    
    to hosted="false":
    <EntityConfig xmlns="urn:sun:fm:SAML:2.0:entityconfig"
        xmlns:fm="urn:sun:fm:SAML:2.0:entityconfig"
        hosted="false"
    
    
  2. Update your metadata files as necessary and include any additional details needed. If you want to map attributes, you can add attribute mapping to the extended metadata file using the following format:
    <Attribute name="attributeMap">
         <Value>EmailAddress=mail</Value>
         <Value>username=uid</Value>
    </Attribute>
    
    Where the first attribute listed (EmailAddress and username in this example) are the attributes used by the entity provider you are creating.
  3. Import the metadata files to create the entity provider in AM/OpenAM:
    $ ./ssoadm import-entity -u [adminID] -f [passwordfile] -e [realmname] -t [entityCOT] -c saml2 -m [metadataXMLfile] -x [extendedXMLfile]
    replacing [adminID], [passwordfile], [realmname], [entityCOT], [metadataXMLfile] and [extendedXMLfile] with appropriate values. You will see the following response if this was successful:
    Import file, [metadataXMLfile].
    Import file, [extendedXMLfile].
Note

You can script these changes to fully automate creating entity providers. See How do I make batch changes using ssoadm in AM/OpenAM (All versions)? for further information on scripting ssoadm commands.

See Also

How do I export and import SAML metadata in AM/OpenAM (All versions)?

How do I update metadata for an IdP or SP in AM/OpenAM (All versions) using ssoadm?

How do I change the metaAlias for an existing IdP or SP in AM/OpenAM (All versions)?

How do I create a hosted IdP or SP in AM/OpenAM (All versions) using ssoadm?

SAML Federation in AM/OpenAM

SAML v2.0 Guide

Reference › Command Line Tools › ssoadm

Related Training

N/A

Related Issue Tracker IDs

OPENAM-3172 (ssoadm create-metadata-templ fails with Exception)


How do I configure a hosted SP as an Attribute Query provider in AM/OpenAM (All versions)?

The purpose of this article is to provide assistance with configuring a hosted SP as an Attribute Query provider in AM/OpenAM. This allows the SP to request attributes about a given subject from the Attribute Authority and then process the attributes received. This article also provides information on configuring a hosted IdP as the Attribute Authority in case you have both a hosted IdP and SP on AM/OpenAM.

Configuring a hosted IdP as the Attribute Authority (optional)

If you have a hosted IdP that you want to act as the Attribute Authority, you need to configure the IdP with the Attribute Authority (AttrAuth) type and map the attributes that will be included in the query from the SP.

To configure your hosted IdP:

  1. On the hosted IdP:
    • AM 6 and later console: navigate to Realms > [Realm Name] > Applications > Federation > Entity Providers, select the check box adjacent to the name of the hosted IdP and click New.
    • AM 5.x console: navigate to: Realms > [Realm Name] > Applications > SAML > Circle of Trust Configuration > Entity Providers, select the check box adjacent to the name of the hosted IdP and click New.
    • Pre-AM 5 console: navigate to: Federation > Circle of Trust Configuration > Entity Providers, select the check box adjacent to the name of the hosted IdP and click New.
  2. Select SAMLv2 as the protocol of the provider.
  3. Complete the following fields on the Create SAMLv2 Entity Provider page:
    • Realm - specify the realm applicable to the IdP.
    • Entity identifier - enter the name of the hosted IdP so it matches the name shown in step 1.
    • Attribute Authority: Meta Alias, Signing certificate alias, Encryption certificate alias - enter a metaAlias applicable to the IdP in the role of Attribute Authority (for example, /attra) and specify the certificate alias values (for example, test to use the test certificate).
  4. Click Create to save your changes. AttrAuth now shows as a Type for your IdP:

  1. Click the name of the hosted IdP entity provider that is of type AttrAuth.
  2. Navigate to IdP > Assertion Processing > Attribute Mapper and enter attribute maps for all the attributes required for the query, for example:
    • cn=cn
    • sn=sn
    • uid=uid
  3. Click Save to save your changes to the IdP.
Note

Ensure you use thread-safe code if you implement the AttributeAuthorityMapper. You can use the attributes on the HttpRequest instead of synchronizing them. The default AttributeAuthorityMapper uses an attribute on the HttpServletRequest to pass information to the AttributeQueryUtil.

Configuring a hosted SP as the Attribute Query provider

If you have a hosted SP that you want to act as the Attribute Query provider, you need to configure the SP with the Attribute Query (AttrQuery) type and map the attributes that will be included in the query.

To configure your hosted SP:

  1. On the hosted SP:
    • AM 6 and later console: navigate to Realms > [Realm Name] > Applications > Federation > Entity Providers, select the check box adjacent to the name of the hosted SP and click New.
    • AM 5.x console: navigate to: Realms > [Realm Name] > Applications > SAML > Circle of Trust Configuration > Entity Providers, select the check box adjacent to the name of the hosted SP and click New.
    • Pre-AM 5 console: navigate to: Federation > Circle of Trust Configuration > Entity Providers, select the check box adjacent to the name of the hosted SP and click New.
  2. Select SAMLv2 as the protocol of the provider.
  3. Complete the following fields on the Create SAMLv2 Entity Provider page:
    • Realm - specify the realm applicable to the SP.
    • Entity identifier - enter the name of the hosted SP so it matches the name shown in step 1.
    • Attribute Query Provider: Meta Alias, Signing certificate alias, Encryption certificate alias - enter a metaAlias applicable to the SP in the role of Attribute Query provider (for example, /attrq) and specify the certificate alias values (for example, test to use the test certificate).
  4. Click Create to save your changes. AttrQuery now shows as a Type for your SP:

  1. Click the name of the hosted SP entity provider that is of type AttrQuery.
  2. Navigate to SP > Assertion Processing > Attribute Mapper and enter attribute maps for all the attributes required for the query, for example:
    • cn=cn
    • sn=sn
    • uid=uid
  3. Click Save to save your changes to the SP.
Note

Ensure you use thread-safe code if you implement the AttributeAuthorityMapper. You can use the attributes on the HttpRequest instead of synchronizing them. The default AttributeAuthorityMapper uses an attribute on the HttpServletRequest to pass information to the AttributeQueryUtil.

  1. On the hosted IdP (if the hosted IdP is on AM/OpenAM):
    • AM 6 and later console: navigate to Realms > [Realm Name] > Applications > Federation > Entity Providers, delete the remote SP entity provider and re-create it to take account of the metadata changes. 
    • AM 5.x console: navigate to: Realms > [Realm Name] > Applications > SAML > Circle of Trust Configuration > Entity Providers, delete the remote SP entity provider and re-create it to take account of the metadata changes.
    • Pre-AM 5 console: navigate to: Federation > Circle of Trust Configuration > Entity Providers, delete the remote SP entity provider and re-create it to take account of the metadata changes. 
  2. On the hosted SP:
    • AM 6 and later console: navigate to Realms > [Realm Name] > Applications > Federation > Entity Providers, delete the remote IdP entity provider and re-create it to take account of the metadata changes. 
    • AM 5.x console: navigate to: Realms > [Realm Name] > Applications > SAML > Circle of Trust Configuration > Entity Providers, delete the remote IdP entity provider and re-create it to take account of the metadata changes. 
    • Pre-AM 5 console: navigate to: Federation > Circle of Trust Configuration > Entity Providers, delete the remote IdP entity provider and re-create it to take account of the metadata changes. 

Calling an endpoint from the SP for an Attribute Query

Once you have configured your SP as an Attribute Query provider, you need to create the following jsp pages:

  • One that creates the AttributeQuery and sends it, for example, AttrQuery.jsp
  • One to handle the response, for example, AttrResp.jsp

There are currently no default pages (such as spSSOInit.jsp) for an Attribute Query from a SP, so you will need to create your own pages based on the sample ones provided for the Fedlet: fedletAttrQuery.jsp and fedletAttrResp.jsp

  • AM / OpenAM 13.5: These files can be found in the /fedlet directory in the fedlet.war file.
  • Pre-OpenAM 13.5: These files can be found in the /saml2/jsp directory in the openam.war file.

See Performing Attribute Queries for further information on using these jsp pages to perform attribute queries for the Fedlet.

Note

You should not use the unspecified nameid format for Attribute Queries because it has not been implemented; you can only use transient or x509.

See Also

How do I export and import SAML metadata in AM/OpenAM (All versions)?

How do I update metadata for an IdP or SP in AM/OpenAM (All versions) using ssoadm?

How do I change the metaAlias for an existing IdP or SP in AM/OpenAM (All versions)?

FAQ: SAML federation in AM/OpenAM

SAML Federation in AM/OpenAM

SAML v2.0 Guide​​​​​​​

Related Training

N/A

Related Issue Tracker IDs

OPENAM-710 (AttributeQuery signature is optional)

OPENAM-6407 (AttributeQuery requests are only accepted if RoleDescriptor with AttributeQueryDescriptorType type is defined in the SP metadata)


How does AM/OpenAM (All versions) use account mapping to identify the end user from a SAML Assertion?

The purpose of this article is to provide information on how AM/OpenAM identifies the end user from a SAML Assertion using account mapping, specifically the NameID element. Understanding account mapping will help you configure SAML federation correctly.

Account mapping in SAML

Note

All of the account mapping related logic is extensible and these features are part of the default implementation (DefaultLibrarySPAccountMapper or DefaultIDPAccountMapper). If you wish to write a custom account mapping mechanism, you can do so by writing a custom Interface SPAccountMapper or a custom Interface IDPAccountMapper. This type of customization is outside the scope of ForgeRock support; if you want more tailored advice, consider engaging Professional Services.

An Assertion can identify an end user either by specifying a unique identifier within the NameID element or by providing SAML attributes within the Assertion to allow the remote entity to perform a lookup based on the provided data.

The NameID value's format is dependent on the NameID-Format being used:

  • The transient and persistent NameID-Formats have additional restrictions on the NameID value; both of them should be an opaque identifier and must not have any relation to the user's identity. In other words, the NameID would look like this:
    <saml:NameID Format="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent" NameQualifier="samlidp" SPNameQualifier="corbinsp">27DbY51ErokOremYdvFBfe9HiHee</saml:NameID>
    This also means that if an IdP sends an Assertion for the first time to an SP, then the user's identity cannot be determined based on just the NameID value. In these scenarios, an AM/OpenAM SP normally just presents the login page to allow the end user to authenticate locally and then, depending on the NameID-Format, a link between the accounts is stored persistently:
    • When using the transient NameID-Format, saving the value is pointless because each SAML authentication with the IdP will result in a different NameID value. 
    • When using the persistent NameID-Format, it is necessary to ensure that the account at the IdP always corresponds to the same account at the SP, hence this link needs to be persisted in the directory server.
  • The unspecified NameID-Format has no restrictions on the actual NameID value, hence it can be anything, even the user's unique identifier across the systems.

You should be aware of the following regarding persistence of the NameID values:

  • It is not possible to disable the persistence for persistent NameID-Format.
  • Transient NameID values are never persisted.
  • It is possible to disable the persistence for unspecified NameID values.
  • The NameID value is persisted for other NameID-Formats in pre-OpenAM 12.0.3 versions; however, as of OpenAM 12.0.3, the SAML2 NameID will not be persisted if the NameID-Format is not persistent. In summary, the NameID persistence logic as of OpenAM 12.0.3 is as follows:
    • Persistent NameID - NameID must be stored.
    • Transient NameID - NameID must not be stored.
    • Ignored user profile mode - NameID cannot be stored (fails if used in combination with persistent NameID-Format).
    • For any other case - NameID may be stored based on customizable logic.     
    See OpenAM 12.0.3 Release Notes › Important Changes to Existing Functionality for further information on these changes.

How does AM/OpenAM identify the end user from the incoming Assertion?

AM/OpenAM identifies the end user from the incoming Assertion based on these concepts:

  • AM/OpenAM uses the local account linking mechanism by default; this means that the user does not have SSO when the transient NameID-Format is used, but for any other NameID-Format, a link is set up between the NameID value and the user account after a successful authentication at the SP.
  • When using the transient NameID-Format, you can set up a Transient User, which means that each logged in user at the SP will be authenticated as that transient user, for example, 'anonymous'.
  • You can also configure AM/OpenAM to handle the NameID value as the User ID, which is mostly useful when using non-transient or non-persistent NameID-Formats; this makes it possible to log users in with NameIDs such as:
    <saml:NameID>jdoe</saml:NameID>
  • You can also use auto federation (which can be combined with the use of NameID as user ID), which allows the setup of an automatic link (without the initial login at the SP) based on the incoming assertion. This also means that SSO works correctly as well.

See Also

FAQ: SAML federation in AM/OpenAM

How do I customize the default SAML2 IdP account mapper in AM/OpenAM (All versions)?

How do I customize the default SAML2 SP account mapper in AM/OpenAM (All versions)?

SAML Federation in AM/OpenAM

OpenAM 13 Release Notes › Changes and Deprecated Functionality › Important Changes to Existing Functionality 

SAML v2.0 Guide​​​​​​​

Related Training

N/A

Related Issue Tracker IDs

OPENAM-11937 (Federation UI does not allow empty NameIDMappingService)

OPENAM-11921 (Incorrect NameId Format offered for SAML2 auth module in console)

OPENAM-3470 (The SAML2 nameid should not be persisted if the nameid-format is not persistent)


How do I configure AM/OpenAM (All versions) to use a Hardware Security Module (HSM) for signing SAML assertions?

The purpose of this article is to provide information on configuring AM/OpenAM to use a Hardware Security Module (HSM) for signing SAML assertions, where the SAML keys are stored in a PKCS11 keystore. AM/OpenAM uses a JCEKS or JKS keystore by default (depending on AM/OpenAM version). It should be noted that HSM protection applies to signing keys only. Symmetric keys used for SAML2 encryption are not generated or stored on the HSM.

Prerequisites

Note

AM/OpenAM supports the PKCS#11 standard interface and you may choose to use your own HSM implementation of this interface. However, when diagnosing issues, ForgeRock may request that a standard provider is used to eliminate HSM-specific issues from the equation.

  1. Install the PKCS11 provider in the Java® Security properties file ($JAVA_HOME/lib/security/java.security) by specifying the sun.security.pkcs11.SunPKCS11 class. For example:
    security.provider.10=sun.security.pkcs11.SunPKCS11 /opt/bar/cfg/pkcs11.cfg 
    Where pkcs11.cfg contains the appropriate configuration for your HSM's PKCS#11 implementation.
  2. Confirm this is working by listing the keystore contents using the following command:
    $ keytool -keystore NONE -storetype PKCS11 -list

See Java PKCS#11 Reference Guide - Configuration and Java PKCS#11 Reference Guide - KeyTool and JarSigner for further information.

You should then follow the instructions in the section applicable to your AM/OpenAM version:

Configuring AM 5 and later

This example process assumes that a private key and certificate alias called mykey already exists in the PKCS11 keystore; however, it is possible that several different aliases could be used in your setup and you will need to adjust this process as necessary.

  1. Update the keystore details using either the console or ssoadm:
    • Console: navigate to: Configure > Server Defaults > Security > Key Store and update the following details:
      • Keystore File - enter the following, where dummy.jks must be a 0 bytes file:
        %BASE_DIR%/%SERVER_URI%/dummy.jks
      • Keystore Type - enter PKCS11.
      • Keystore Password File - enter the following, where .pass contains the plain text password for the HSM.  
        %BASE_DIR%/%SERVER_URI%/.pass
      • Private Key Password File - enter the following, where .privatepass contains the plain text key password for the alias. If the key alias password matches the key store password, you can just set this field the same as above.  
        %BASE_DIR%/%SERVER_URI%/.privatepass
    • ssoadm: enter the following command:
      $ ./ssoadm update-server-cfg -s default -u [adminID] -f [passwordfile] -a com.sun.identity.saml.xmlsig.keystore=%BASE_DIR%/%SERVER_URI%/dummy.jks com.sun.identity.saml.xmlsig.storetype=PKCS11 com.sun.identity.saml.xmlsig.storepass=%BASE_DIR%/%SERVER_URI%/.pass com.sun.identity.saml.xmlsig.keypass=%BASE_DIR%/%SERVER_URI%/.privatepass 
      replacing [adminID] and [passwordfile] with appropriate values.
Note

The Certificate Alias field in this section relates to the SAML 1.x default signing key and should only be modified if applicable to your setup.

  1. Create the 0 byte dummy.jks file and the password file(s) that you referenced in step 1.
  2. Update the metadata signing key alias (mykey in this example) using either the console or ssoadm:
    • Console: navigate to: Configure > Global Services > SAMLv2 Service Configuration > Realm Defaults > Metadata signing key alias and update it to: mykey. You can leave the Metadata signing key password unchanged.
    • ssoadm: enter the following command:
      $ ./ssoadm set-attr-defs -s sunFAMSAML2Configuration -t organization -u [adminID] -f [passwordfile] -a metadataSigningKey=mykey
      replacing [adminID] and [passwordfile] with appropriate values.
  3. Update the certificate alias (mykey in this example) in the top level realm using either the console or ssoadm:
    • Console: navigate to: Realms > Top Level Realm / > Authentication > Settings > Security > Persistent Cookie Encryption Certificate Alias and update it to: mykey.
    • ssoadm: enter the following command:
      $ ./ssoadm set-realm-svc-attrs -s iPlanetAMAuthService -e / -u [adminID] -f [passwordfile] -a iplanet-am-auth-key-alias=mykey
      
      replacing [adminID] and [passwordfile] with appropriate values.
  4. Create your hosted IdP or SP if you haven't already done so.
  5. Select the hosted IdP or SP:
    • AM 6 and later console: navigate to Realms > [Realm Name] > Applications > Federation > Entity Providers and selecting the hosted IdP or SP.
    • AM 5.x console: navigate to: Realms > [Realm Name] > Applications > SAML > Circle of Trust Configuration > Entity Providers and selecting the hosted IdP or SP.
  6. Navigate to Assertion Content > Signing and Encryption > Certificate Aliases > Signing and enter: mykey. Leave the Key Pass field blank to use the password stored in %BASE_DIR%/%SERVER_URI%/.pass.
  7. Confirm that the metadata is signed using the expected key and certificate via the REST API using a command similar to the following:
    $ curl http://host1.example.com:8080/openam/saml2/jsp/exportmetadata.jsp?sign=true

Configuring OpenAM 13.5.x and earlier

This example process assumes that a private key and certificate alias called mykey already exists in the PKCS11 keystore; however, it is possible that several different aliases could be used in your setup and you will need to adjust this process as necessary. Additionally, it assumes you have installed the ampassword administration tool.

  1. Update the password files using either the console or ssoadm:
    • OpenAM 13.5 console: navigate to: Configure > Server Defaults > Security > Key Store and update both Keystore Password File and Private Key Password File to:
      %BASE_DIR%/%SERVER_URI%/.mypass
    • Pre-OpenAM 13.5 console: navigate to: Configuration > Servers and Sites > Default Server Settings > Security > Key Store and update both Keystore Password File and Private Key Password File to:
      %BASE_DIR%/%SERVER_URI%/.mypass
    • ssoadm: enter the following command:
      $ ./ssoadm update-server-cfg -s default -u [adminID] -f [passwordfile] -a com.sun.identity.saml.xmlsig.storepass=%BASE_DIR%/%SERVER_URI%/.mypass com.sun.identity.saml.xmlsig.keypass=%BASE_DIR%/%SERVER_URI%/.mypass
      replacing [adminID] and [passwordfile] with appropriate values.
Note

The Certificate Alias field in this section relates to the SAML 1.x default signing key and should only be modified if applicable to your setup.

  1. Change the keystore type to PKCS11 using either the console or ssoadm:
    • OpenAM 13.5 console: navigate to: Configure > Server Defaults > Security > Key Store and update the Keystore Type to PKCS11.
    • Pre-OpenAM 13.5 console: navigate to: Configuration > Servers and Sites > Default Server Settings > Advanced and add the following new property and value:
      com.sun.identity.saml.xmlsig.storetype = PKCS11
    • ssoadm: enter the following command:
      $ ./ssoadm update-server-cfg -s default -u [adminID] -f [passwordfile] -a com.sun.identity.saml.xmlsig.storetype=PKCS11
      replacing [adminID] and [passwordfile] with appropriate values.
  2. Update the metadata signing key alias (mykey in this example) using either the console or ssoadm:
    • OpenAM 13.5 console: navigate to: Configure > Global Services > SAMLv2 Service Configuration > Realm Attributes > Metadata signing key alias and update it to: mykey. You can leave the Metadata signing key password unchanged.
    • Pre-OpenAM 13.5 console: navigate to: Configuration > Global > SAMLv2 Service Configuration > Realm Attributes > Metadata signing key alias and update it to: mykey. You can leave the Metadata signing key password unchanged.
    • ssoadm: enter the following command:
      $ ./ssoadm set-attr-defs -s sunFAMSAML2Configuration -t organization -u [adminID] -f [passwordfile] -a metadataSigningKey=mykey
      replacing [adminID] and [passwordfile] with appropriate values.
  3. Update the certificate alias (mykey in this example) in the top level realm using either the console or ssoadm:
    • OpenAM 13.x console: navigate to: Realms > Top Level Realm / > Authentication > Settings > Security > Persistent Cookie Encryption Certificate Alias and update it to: mykey.
    • Pre-OpenAM 13 console: navigate to: Access Control > / (Top Level Realm) > Authentication > All Core Settings > Security > Organization Authentication Certificate Alias and update it to: mykey.
    • ssoadm: enter the following command:
      $ ./ssoadm set-realm-svc-attrs -s iPlanetAMAuthService -e / -u [adminID] -f [passwordfile] -a iplanet-am-auth-key-alias=mykey
      
      replacing [adminID] and [passwordfile] with appropriate values.
  4. Create the password for your HSM using the following command:
    $ ./ampassword -e pw.txt > .mypass
  5. Shutdown the web application container in which OpenAM runs.
  6. Copy the output .mypass file to %BASE_DIR%/%SERVER_URI%/; this is the location of the Keystore and Private Key password files that you specified in step 1. 
  7. Blank out the contents of the keystore.jceks or keystore.jks file (typically located in the $HOME/openam/openam/ directory) to remove the default keystore. This file must exist as its presence is checked when OpenAM initializes but its contents will not be used.
  8. Create your hosted IdP or SP if you haven't already done so.
  9. Select the hosted IdP or SP by navigating to: Federation > Circle of Trust Configuration > Entity Providers and select the hosted IdP or SP.
  10. Navigate to Assertion Content > Signing and Encryption > Certificate Aliases > Signing and enter: mykey. Leave the Key Pass field blank to use the password stored in %BASE_DIR%/%SERVER_URI%/.mypass.
  11. Confirm that the metadata is signed using the expected key and certificate via the REST API using a command similar to the following:
    $ curl http://host1.example.com:8080/openam/saml2/jsp/exportmetadata.jsp?sign=true

See Also

How do I create persistent SAML federation between two AM/OpenAM servers where user attributes match?

How do I change the Signing Key for Federation in OpenAM 12.x and 13.x?

Installation Guide › Installing and Starting Servers › Installing and Using the Tools

Reference › Command Line Tools › ampassword

Setup and Maintenance Guide › Changing Default Key Aliases

SAML v2.0 Guide

Java PKCS#11 Reference Guide - Configuration

Java PKCS#11 Reference Guide - KeyTool and JarSigner

Related Training

N/A

Related Issue Tracker IDs

OPENAM-11249 (Ability to store all keys and secrets in a HSM)

OPENAM-3863 (OpenAM should offer a way to use a Hardware Security Module (HSM) for signing / encrypting SAML assertions)


How do I configure how long the SAML AuthnRequest remains in cache in AM/OpenAM (All versions)?

The purpose of this article is to provide information on configuring how long the SAML AuthnRequest (request ID) remains in the cache in AM/OpenAM. By default, the cache is cleared every 10 minutes. Cached details include the AuthRequest and the artifact ID.

Overview

The cache is cleared every 10 minutes by default, but you may want to consider increasing this interval if you keep seeing the following error in the Federation debug log:

ERROR: IDPSSOFederate.doSSOFederate: Unable to get AuthnRequest from cache, sending error response

This error means that the SAML AuthnRequest is missing from the local cache; this can be caused by timeout or by a misrouted request in a multi-instance environment where stickiness is not available. If it is a timeout issue, increasing the cache cleanup interval would prevent these errors.

Configuring how long the SAML AuthnRequest remains in the cache

You can configure how long the SAML AuthnRequest remains in the cache using either the console or ssoadm:

  • AM / OpenAM 13.x console: navigate to: Configure > Global Services > SAMLv2 Service Configuration > Cache cleanup interval and enter the number of seconds that you want the AuthnRequest to remain in the cache. Once this time elapses, the cache is cleared.
  • Pre-OpenAM 13.5 console: navigate to: Configuration > Global > SAMLv2 Service Configuration > Cache cleanup interval and enter the number of seconds that you want the AuthnRequest to remain in the cache. Once this time elapses, the cache is cleared.
  • ssoadm: enter the following command:
    $ ./ssoadm set-attr-defs -s sunFAMSAML2Configuration -t global -u [adminID] -f [passwordfile] -a CacheCleanupInterval=[seconds]
    replacing [adminID], [passwordfile] and [seconds] with appropriate values.
Note

You must restart the web application container in which AM/OpenAM runs to apply these configuration changes.

Caution

You cannot disable this cache; setting the Cache cleanup interval to 0 will cause a divide by zero exception during initialization of the SPCache: "java.lang.ArithmeticException: / by zero".

See Also

SAML Federation in AM/OpenAM

SAML v2.0 Guide

Related Training

N/A

Related Issue Tracker IDs

OPENAM-4590 (Improve dealing with "Return to login" link when using SAML federation)

OPENAM-8510 (com.sun.identity.saml2.cacheCleanUpInterval should only accept values > 0)


How do I configure IdP or SP initiated Single Sign On in AM/OpenAM (All versions)?

The purpose of this article is to provide information on configuring IdP or SP initiated Single Sign On (SSO) in AM/OpenAM.

Configuring IdP or SP initiated Single Sign On

There are two JSP pages that you can include in the URL that you are calling when a user logs in to initiate SSO depending on whether it is IdP or SP initiated: idpSSOInit.jsp or spSSOInit.jsp respectively. For example, the following URL would provide single sign on initiated by the SP: 

http://sp.example.com:8080/openam/saml2/jsp/spSSOInit.jsp?metaAlias=/sp&idpEntityID=http%3A%2F%2Fidp.acme.com%3A8080%2Fopenam

Optionally, you can call the jsp using idpssoinit or spssoinit under the context root instead. For example, the following URL would provide single sign on initiated by the IdP:

http://idp.acme.com:8080/openam/idpssoinit?metaAlias=/idp&spEntityID=http%3A%2F%2Fsp.example%3A8080%2Fopenam

You can then specify the required parameters in the URL to control the resulting login behavior, using & to separate different parameters. See SAML v2.0 Guide › Implementing SAML v2.0 Using the AM Console › JSP Pages for SSO and SLO for further information on these parameters.

The metaAlias parameter must be included in an IdP or SP initiated login URL, and either the spEntityID parameter (for IdP initiated logins) or the idpEntityID parameter (for SP initiated logins):

  • metaAlias - this specifies the local alias for the provider in the format /realmname/providername. For the top level realm, exclude the realmname element, that is, just include /providername. 
  • spEntityID - this specifies the remote service provider (for IdP initiated logins) and must be URL encoded, for example, for remote service provider http://sp.example:8080/openam, you would specify:
    http%3A%2F%2Fsp.example%3A8080%2Fopenam
  • idpEntityID - this specifies the remote identity provider (for SP initiated logins) and must be URL encoded.

See Also

How do I redirect to a specific page after a successful IdP or SP initiated login in AM/OpenAM (All versions)?

SP initiated login fails in AM/OpenAM (All versions) with Service Provider ID is null error

How do I configure IdP or SP initiated Single Logout in AM/OpenAM (All versions)?

FAQ: SAML federation in AM/OpenAM

SAML Federation in AM/OpenAM

SAML v2.0 Guide › Implementing SAML v2.0 Using the AM Console › JSP Pages for SSO and SLO

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs

N/A


How do I redirect to a specific page after a successful IdP or SP initiated login in AM/OpenAM (All versions)?

The purpose of this article is to provide information on redirecting the user to a specific page after a successful federated Single Sign On (SSO) in AM/OpenAM. The SSO can be either IdP or SP initiated.

Redirecting the user after SSO

You can redirect the user to a specific page after SSO using either the RelayState parameter or the goto parameter. The RelayState parameter takes precedence over the goto parameter.

If you use the RelayState parameter, you must URL encode this value in the URL. For example, to redirect to http://host1.example.com, you would need to use:

RelayState=http%3A%2F%2Fhost1.example.com

You should append the RelayState parameter or goto parameter and the required redirect URL to the login URL.

Note

The login URL is specified against the agent as described in the Agent User Guides: Configuring Access Management Services Properties (Web) and Configuring AM Services Properties (Java).

Example Login URLs

The following example URLs show an IdP and SP initiated SSO, where the lines are folded to show you the query string parameters:

  • Using the RelayState parameter with an IdP initiated SSO and HTTP-POST binding:
    http://idp.acme.com:8080/openam/idpssoinit
    ?metaAlias=/idp
    &spEntityID=http%3A%2F%2Fsp.example.com%3A8080%2Fopenam
    &binding=urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST
    &RelayState=http%3A%2F%2Fhost1.example.com
  • Using the RelayState parameter with a SP initiated SSO:
    http://sp.example.com:8080/openam/saml2/jsp/spSSOInit.jsp
    ?metaAlias=/sp
    &idpEntityID=http%3A%2F%2Fidp.acme.com%3A8080%2Fopenam
    &RelayState=http%3A%2F%2Fsp.example.com%3A8080%2Fopenam%2Fidm%2FEndUser
    

Improving security for redirects

To improve security, you can also specify a list of valid URLs for the RelayState parameter and a list of valid URL resources for the goto parameter.

RelayState parameter

When you specify a URL list, the URL stated in the RelayState parameter must exist on the URL list for the user to be redirected. If you do not specify a URL list, all URLs specified in the RelayState parameter are considered valid.

You can configure this URL list in the console once you have set up your IdP or SP:

  • AM 6 and later console: navigate to Realms > [Realm Name] > Applications > Federation > Entity Providers > [Provider Name] > Advanced > Relay State URL List and add the valid RelayState URLs.
  • AM 5.x console: navigate to: Realms > [Realm Name] > Applications > SAML > Circle of Trust Configuration > Entity Providers > [Provider Name] > Advanced > Relay State URL List and add the valid RelayState URLs.
  • Pre-AM 5 console: navigate to: Federation > Circle of Trust Configuration > Entity Providers > [Provider Name] > Advanced > Relay State URL List and add the valid RelayState URLs.

See the SAML v2.0 Guide for further information on the Relay State URL List - IdP and SP.

goto parameter

When you specify a URL resource list, the resource of the URL stated in the goto parameter must exist on the URL resource list for the user to be redirected. If you do not specify a URL resource list, all resources included in URLs specified in the goto parameter are considered valid.

See How do I configure a list of valid goto URL resources in AM/OpenAM (All versions)? for further information.

Using the RelayState parameter with the SAML2ServiceProviderAdapter doing the SSO

When using a SAML2ServiceProviderAdapter to do SSO using the postSingleSignOnSuccess() method, the RelayState parameter will return a random string during a SP initiated SSO. This is in line with the SAML spec -  the SP generates a random string and sends that as the ID of the RelayState and the IdP blindly returns the string. The SP should then decode that string and redirect to the actual URL.

To ensure the SP does decode this string, you need to use the SPCache.relayStateHash method to convert the string back to a URL. For example, using code similar to the following:

CacheObject c = (CacheObject) SPCache.relayStateHash.get(idpSuppliedGotoURL);

if (c != null) { 
idpSuppliedGotoURL = (String) c.getObject();

See Also

How do I configure a list of valid goto URL resources in AM/OpenAM (All versions)?

How do I configure IdP or SP initiated Single Sign On in AM/OpenAM (All versions)?

How do I redirect to a specific page after a successful IdP or SP initiated logout in AM/OpenAM (All versions)?

FAQ: SAML federation in AM/OpenAM

SAML Federation in AM/OpenAM

SAML v2.0 Guide › Implementing SAML v2.0 Using the AM Console › JSP Pages for SSO and SLO

API Javadoc › Class SAML2ServiceProviderAdapter

Bindings for the OASIS Security Assertion Markup Language (SAML) V2.0

Related Training

N/A

Related Issue Tracker IDs

OPENAM-11956 (SAML2 RelayState values are seen as invalid if they are not a URL which appears to go against the spec)

OPENAM-3679 (IDP Finder fails to validate relaystate)


How do I configure IdP or SP initiated Single Logout in AM/OpenAM (All versions)?

The purpose of this article is to provide information on configuring IdP or SP initiated Single Logout (SLO) in AM/OpenAM.

Background information

When a user signs into an IdP and multiple SPs using Single Sign On, the IdP keeps track of all the SPs that it is has sent an authentication response to. When the user subsequently logs out from one SP, the IdP knows which other SPs they are logged in to and can send logout requests.

There are two JSP pages that you can include in the URL that you are calling when a user logs out to initiate SLO depending on whether it is IdP or SP initiated: idpSingleLogoutInit.jsp or spSingleLogoutInit.jsp respectively. For example:

  • The following URL would provide single logout initiated by the IdP:
    http://idp.acme.com:8080/openam/saml2/jsp/idpSingleLogoutInit.jsp?metaAlias=/idp&spEntityID=SP&binding=urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST
    
  • The following URL would provide single logout initiated by the SP:
    http://sp.example.com:8080/openam/saml2/jsp/spSingleLogoutInit.jsp?metaAlias=/sp&idpEntityID=http%3A%2F%2Fidp.acme.com%3A8080%2Fopenam
    

Optionally, you can call the jsp using IDPSloInit or SPSloinit under the context root instead. For example: 

  • The following URL would provide single logout initiated by the IdP:
    http://idp.acme.com:8080/openam/IDPSloInit?binding=urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST
  • The following URL would provide single logout initiated by the SP:
    http://sp.example:8080/openam/SPSloInit?metaAlias=/sp&idpEntityID=http%3A%2F%2Fidp.acme.com%3A8080%2Fopenam
    

You can specify other parameters in the URL to control the resulting log out behavior using & to separate different parameters. See the Logout URL guidelines section below for further information to help you construct your URLs.

Note

It is the IdP's responsibility to decide where to send the logout requests; you can use the logoutAll parameter for an IdP initiated logout URL, which sends a logout request to all service providers (regardless of whether they have an active session or not) to override the IdP's decisions.

Logout URL guidelines

You should be aware of the following guidelines to ensure your logout URL functions as expected:

SP initiated logout URL

  • You must include either idpEntityID or binding in your URL, unless you use HTTP Redirect binding:
  • If you use HTTP Redirect binding, you must include both idpEntityID and binding (HTTP Redirect binding is the default binding used when binding is not specified).
  • metaAlias is optional when you specify idpEntityID although recommended.
  • idpEntityID is always required for fedlets.
  • idpEntityID should be URL encoded.

IdP initiated logout URL

  • You must include binding in your URL.
  • metaAlias is optional when you specify spEntityID although recommended.

See SAML v2.0 Guide › Implementing SAML v2.0 Using the AM Console › JSP Pages for SSO and SLO for further information on these parameters.  

Binding options

You can use one of the following binding values:

  • binding=urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect, which uses the HTTP Redirect binding. This binding is the default option and all communications between IdPs and SPs are through the browser using a URL query string, which means direct connections are not required; the IdP bounces the browser back and forth between each SP to achieve logout. The potential downside to this approach is if an IdP or SP fails to respond, some sessions may be left active and the user could end up stuck on an error page part way through the logout process.
  • binding=urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST, which uses the HTTP POST binding. This binding is also commonly used and all communications between IdPs and SPs are through the browser using a self submitting XHTML form; again direct connections are not required and the IdP bounces the browser back and forth between each SP to achieve logout, resulting in the same potential downside as the HTTP Redirect binding.
  • binding=urn:oasis:names:tc:SAML:2.0:bindings:SOAP (IdP only), which uses the SOAP binding. This binding sends direct communications on a back channel between IdPs and SPs (requiring direction connections), which overcomes the possibility of an IdP or SP failing to respond via the browser. However, message encoding is more complicated.
  • binding=urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact (SP only), which uses the HTTP Artifact binding. This binding uses the Artifact Resolution Protocol and the SOAP binding for its direct communications between IdPs and SPs; it is therefore similar to the SOAP binding but suitable for SP initiated logouts.

See How do I know which binding to use for SAML2 federation in AM/OpenAM (All versions)? for further information. 

Caution

For the binding parameter, you must use the full long name, for example, urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST instead of HTTP-POST, otherwise you will get a HTTP-400 error (Requested binding is not supported).

See Also

How do I redirect to a specific page after a successful IdP or SP initiated logout in AM/OpenAM (All versions)?

How do I know which binding to use for SAML2 federation in AM/OpenAM (All versions)?

SP initiated logout fails in AM/OpenAM (All versions) with Identity Provider ID is null error

How do I configure IdP or SP initiated Single Sign On in AM/OpenAM (All versions)?

FAQ: SAML federation in AM/OpenAM

SAML Federation in AM/OpenAM

SAML v2.0 Guide › Implementing SAML v2.0 Using the AM Console › JSP Pages for SSO and SLO

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs

OPENAM-3202 (RelayState is validated as a URL)

OPENAM-3437 (RelayState validation fails during SLO)


How do I redirect to a specific page after a successful IdP or SP initiated logout in AM/OpenAM (All versions)?

The purpose of this article is to provide information on redirecting the user to a specific page after a successful Single Logout (SLO) in AM/OpenAM. The SLO can be either IdP or SP initiated. If you do not specify a page, the default.jsp page is shown which just informs you of a successful single logout.

Redirecting the user after SLO

You can redirect the user to a specific page after SLO using either the RelayState parameter or the goto parameter. The RelayState parameter takes precedence over the goto parameter.

If you use the RelayState parameter, you must URL encode this value in the URL. For example, to redirect to http://host1.example.com, you would need to use:

RelayState=http%3A%2F%2Fhost1.example.com

You should append the RelayState or goto parameter and the required redirect URL to the logout URL.

Note

The logout URL is specified against the agent as described in the Agent User Guides: Configuring Access Management Services Properties (Web) and Configuring AM Services Properties (Java).

Example IdP Logout URLs

The following example URLs show IdP initiated SLO, where the lines are folded to show you the query string parameters:

  • Using the RelayState parameter with an IdP initiated SLO and HTTP-POST binding (idpSingleLogoutInit.jsp):
    http://idp.acme.com:8080/openam/saml2/jsp/idpSingleLogoutInit.jsp
    ?metaAlias=/idp
    &spEntityID=SP
    &binding=urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST
    &RelayState=http%3A%2F%2Fhost1.example.com
  • Using the RelayState parameter with an IdP initiated SLO and HTTP-POST binding (IDPSloInit), depending on version:
    • AM 5 and later:
      http://idp.acme.com:8080/openam/IDPSloInit
      ?metaAlias=/idp
      &spEntityID=SP
      &reqBinding=urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST
      &RelayState=http%3A%2F%2Fhost1.example.com
    • Pre-AM 5:
      http://idp.acme.com:8080/openam/IDPSloInit
      ?binding=urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST
      &RelayState=http%3A%2F%2Fhost1.example.com

Example SP Logout URLs

The following example URLs show SP initiated SLO, where the lines are folded to show you the query string parameters:

  • Using the RelayState parameter with a SP initiated SLO (spSingleLogoutInit.jsp):
    http://sp.example.com:8080/openam/saml2/jsp/spSingleLogoutInit.jsp
    ?idpEntityID=http%3A%2F%2Fidp.acme.com%3A8080%2Fopenam
    ​&RelayState=http%3A%2F%2Fexample.com
    
  • Using the RelayState parameter with a SP initiated SLO (SPSloInit):
    http://sp.example:8080/openam/SPSloInit
    ?metaAlias=/sp
    &idpEntityID=http%3A%2F%2Fidp.acme.com%3A8080%2Fopenam
    &RelayState=http%3A%2F%2Fexample.com 
  • Using the goto parameter with a SP initiated SLO and HTTP-Redirect binding:
    http://sp.example:8080/openam/saml2/jsp/spSingleLogoutInit.jsp
    ?idpEntityID=http%3A%2F%2Fidp.acme.com%3A8080%2Fopenam
    &binding=urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect
    &goto=http://forgerock.com

Improving security for redirects

To improve security, you can also specify a list of valid URLs for the RelayState parameter and a list of valid URL resources for the goto parameter.

RelayState parameter

When you specify a URL list, the URL stated in the RelayState parameter must exist on the URL list for the user to be redirected. If you do not specify a URL list, all URLs specified in the RelayState parameter are considered valid.

You can configure this URL list in the console once you have set up your IdP or SP:

  • AM 6 and later console: navigate to Realms > [Realm Name] > Applications > Federation > Entity Providers > [Provider Name] > Advanced > Relay State URL List and add the valid RelayState URLs.
  • AM 5.x console: navigate to: Realms > [Realm Name] > Applications > SAML > Circle of Trust Configuration > Entity Providers > [Provider Name] > Advanced > Relay State URL List and add the valid RelayState URLs.
  • Pre-AM 5 console: navigate to: Federation > Circle of Trust Configuration > Entity Providers > [Provider Name] > Advanced > Relay State URL List and add the valid RelayState URLs.

See the SAML v2.0 Guide for further information on the Relay State URL List - IdP and SP.

goto parameter

When you specify a URL resource list, the resource of the URL stated in the goto parameter must exist on the URL resource list for the user to be redirected. If you do not specify a URL resource list, all resources included in URLs specified in the goto parameter are considered valid.

See How do I configure a list of valid goto URL resources in AM/OpenAM (All versions)? for further information.

See Also

How do I configure IdP or SP initiated Single Logout in AM/OpenAM (All versions)?

How do I redirect to a specific page after a successful IdP or SP initiated login in AM/OpenAM (All versions)?

FAQ: SAML federation in AM/OpenAM

SAML Federation in AM/OpenAM

Installation Guide › Securing Installations › Avoiding Obvious Defaults

SAML v2.0 Guide › Implementing SAML v2.0 Using the AM Console › JSP Pages for SSO and SLO

Related Training

N/A

Related Issue Tracker IDs

OPENAM-3202 (RelayState is validated as a URL)

OPENAM-3437 (RelayState validation fails during SLO)


How do I know which binding to use for SAML2 federation in AM/OpenAM (All versions)?

The purpose of this article is to provide information on using bindings for SAML2 federation in AM/OpenAM. There are two different concepts to bindings in SAML2; the binding used for the communication, including sending the request, and the protocol binding, which is used when returning the response message. This article focuses on standalone mode, in which you invoke JSPs to initiate SSO and SLO, but the principles apply if you use integrated mode, in which you configure a SAML2 authentication module.

Communication bindings

Communication bindings correspond to the method used for communications between the SP and the IdP.

For the authentication request, the communication can be sent through HTTP-POST or HTTP-REDIRECT (GET).

HTTP-REDIRECT is used by default when you use spSSOInit.jsp. If you want to use HTTP-POST, you need to add the reqBinding parameter to the URL, for example:

http://sp.example.com:8080/openam/saml2/jsp/spSSOInit.jsp?idpEntityID=http%3A%2F%2Fidp.acme.com%3A8080%2Fopenam&metaAlias=/sp&reqBinding=urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST

If you are the IdP and do not want to, or cannot accept HTTP-REDIRECT, you can inform the SP by not providing the corresponding endpoint. For example, if AM/OpenAM is the IdP and you want to prevent access to http://idp.acme.com:8080/openam/SSORedirect/metaAlias/idp, you should configure the IdP as follows:

  1. Select the IdP entity provider:
    • AM 6 and later console: navigate to Realms > [Realm Name] > Applications > Federation > Entity Providers and click the name of the entity provider that is of type Hosted IdP.
    • AM 5.x console: navigate to Realms > [Realm Name] > Applications > SAML > Circle of Trust Configuration > Entity Providers and click the name of the entity provider that is of type Hosted IdP.
    • Pre-AM 5 console: navigate to: Federation > Circle of Trust Configuration > Entity Providers and click the name of the entity provider that is of type Hosted IdP.
  2. Navigate to Services > Single SignOn Service and remove the entry in the HTTP-REDIRECT Location field.
  3. Inform the SP that the metadata has changed and they need to update their configuration accordingly. This ensures the SP knows it cannot send a GET request to that endpoint.

For the following JSP pages, you can also specify the communication binding to use for the entire communication by adding the binding parameter to the URL:

  • spSSOInit.jsp
  • idpSSOInit.jsp
  • idpSingleLogoutInit.jsp
  • spSingleLogoutInit.jsp
  • idpMNIRequestInit.jsp
  • spMNIRequestInit.jsp

For example, if you want to use SOAP (machine to machine communication) for SLO via idpSingleLogoutInit.jsp, you would need to specify the binding parameter in the URL as follows:

http://idp.acme.com:8080/openam/saml2/jsp/idpSingleLogoutInit.jsp?metaAlias=/sp&idpEntityID=http%3A%2F%2Fidp.example.com%3A8080%2Fopenam&binding=urn:oasis:names:tc:SAML:2.0:bindings:SOAP

See SAML v2.0 Guide › Implementing SAML v2.0 Single Sign-On and Single Logout for further information on which bindings are available for which JSP pages.

Protocol bindings

Protocol bindings correspond to the protocol to use when returning the Response message:

  • With HTTP-Artifact, the IdP sends a nonce (a unique number working as a reference) back to the SP and the SP does a server-to-server communication using that nonce to retrieve the assertion. 
  • With HTTP-POST, the IdP sends the assertion back through the user-agent directly. 

The flow used is defined on the SP side. If AM/OpenAM is the SP,  you can change this as follows:

  1. Select the SP entity provider:
    • AM 6 and later console: navigate to Realms > [Realm Name] > Applications > Federation > Entity Providers and click the name of the entity provider that is of type Hosted SP.
    • AM 5.x console: navigate to Realms > [Realm Name] > Applications > SAML > Circle of Trust Configuration > Entity Providers and click the name of the entity provider that is of type Hosted SP.
    • Pre-AM 5 console: navigate to: Federation > Circle of Trust Configuration > Entity Providers and click the name of the entity provider that is of type Hosted SP.
  2. Navigate to Services > Assertion Consumer Service and select the required binding. This defaults to HTTP-Artifact.
  3. Inform the IdP that the metadata has changed and they need to update their configuration accordingly.
Note

The protocol binding is optional in a <AuthnRequest> message as per the SAML spec: Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) V2.0 (3.4.1 Element <AuthnRequest>).

See Also

How do I update metadata for an IdP or SP in AM/OpenAM (All versions) using ssoadm?

FAQ: SAML federation in AM/OpenAM

SAML Federation in AM/OpenAM

SAML v2.0 Guide

Authentication and Single Sign-On Guide › Implementing Authentication › SAML2 Authentication Module​​​​​​​

Related Training

N/A

Related Issue Tracker IDs

N/A


Managing SAML Certificates


How do I rollover certificates for an IdP or SP in AM (All versions) and OpenAM 13.x?

The purpose of this article is to provide information on performing key rollover for federation certificates (signing and encryption) in AM/OpenAM. This article includes steps for hosted and remote entity providers. It assumes you already have federation set up and working correctly, and your new certificates have already been imported into your AM/OpenAM keystore for hosted entity providers.

Overview

AM/OpenAM does not check for the certificate expiration date as discussed in FAQ: SAML certificate management in AM/OpenAM (Q. Why isn't the SAML certificate expiration date checked?)

However, AM/OpenAM does support multiple signing keys to allow for key rollover; this means you can cutover to a new certificate when the current one is either revoked or expires.

This article covers the different ways you can perform key rollover:

Caution

These instructions assume you have already imported the new certificate in to the AM/OpenAM keystore for hosted entity providers, it has a different alias to the existing one and it is ready for use.

AM/OpenAM keystore

AM/OpenAM uses a JCEKS keystore as its default keystore as of OpenAM 13.5. The default location is: %BASE_DIR%/%SERVER_URI%/keystore.jceks; you can change this by navigating to: Configure > Server Defaults > Security > Key Store > Keystore File.

OpenAM 13.0 stores its default signing key in a Java Keystore file located in the $HOME/openam/openam/keystore.jks; you can check the location of this keystore in the OpenAM console by navigating to: Configuration > Servers and Sites > Default Server Settings > Security > Key Store.

Note

It is recommended that you make a backup of your keystore.jceks | keystore.jks.keypass and .storepass files before making any changes.

Testing federation

Throughout these procedures, you can verify federation is working with updated metadata files using the following calls to initiate the SAML flow:

  • SP initiated login URL:
    http://sp.example.com:8080/openam/saml2/jsp/spSSOInit.jsp?metaAlias=/sp&idpEntityID=http%3A%2F%2Fidp.acme.com%3A8080%2Fopenam
    
  • IdP initiated login URL:
    http://idp.acme.com:8080/openam/idpSSOinit.jsp?metaAlias=/idp&spEntityID=http%3A%2F%2Fsp.example.com%3A8080%2Fopenam
    

Replace the example FQDNs and port numbers with the appropriate values for your IdP and SP.

Performing key rollover for hosted entity providers (console)

You can perform key rollover for hosted entity providers via the console as follows:

  1. Navigate to: 
    • AM 6 and later console: navigate to Realms > [Realm Name] > Applications > Federation > Entity Providers > [Provider Name] > Assertion Content > Signing and Encryption > Certificate Aliases.
    • AM 5.x console: navigate to: Realms > [Realm Name] > Applications > SAML > Circle of Trust Configuration > Entity Providers > [Provider Name] > Assertion Content > Signing and Encryption > Certificate Aliases.
    • OpenAM 13.x console: navigate to: Federation > Circle of Trust Configuration > Entity Providers > [Provider Name] > Assertion Content > Signing and Encryption > Certificate Aliases.
  2. Add a new alias to the list of Signing and/or Encryption aliases. AM/OpenAM uses the first certificate listed.
  3. Export the updated metadata - you can export it via the browser, a curl command or ssoadm as detailed in How do I export and import SAML metadata in AM/OpenAM (All versions)?
  4. Provide the updated metadata to the remote SP or IdP. 
  5. Remove the original alias from the list of Signing and/or Encryption aliases at the point you want to rollover to the new certificate.
  6. Export the updated metadata.
  7. Provide the updated metadata to the remote SP or IdP. 

See SAML v2.0 Guide › Reference › Assertion Content (IdP) and SAML v2.0 Guide › Reference › Assertion Content (SP) for further information on certificate aliases used for signing keys.

Performing key rollover for remote entity providers (console)

You can perform key rollover for remote entity providers via the console as follows:

  1. Receive the first updated metadata file from the entity provider. This file will contain both the old and new aliases.
  2. Remove the remote entity provider configuration before importing the modified metadata files:
    • AM 6 and later console: navigate to Realms > [Realm Name] > Applications > Federation > Entity Providers, select the check box next to the entity provider you want to delete and click Delete. 
    • AM 5.x console: navigate to: Realms > [Realm Name] > Applications > SAML > Circle of Trust Configuration > Entity Providers, select the check box next to the entity provider you want to delete and click Delete. 
    • OpenAM 13.x console: navigate to: Federation > Circle of Trust Configuration > Entity Providers, select the check box next to the entity provider you want to delete and click Delete. 
  3. Import the received metadata:
    • AM 6 and later console: navigate to Realms > [Realm Name] > Applications > Federation > Entity Providers, click Import Entity, specify the URLs of the metadata files and click OK. 
    • AM 5.x console: navigate to: Realms > [Realm Name] > Applications > SAML > Circle of Trust Configuration > Entity Providers, click Import Entity, specify the URLs of the metadata files and click OK. 
    • OpenAM 13.x console: navigate to: Federation > Circle of Trust Configuration > Entity Providers, click Import Entity, specify the URLs of the metadata files and click OK. 
  4. Verify federation is still working with the updated metadata file.
  5. Receive the second updated metadata file from the entity provider containing the new alias.
  6. Remove the remote entity provider configuration before importing the modified metadata files:
    • AM 6 and later console: navigate to Realms > [Realm Name] > Applications > Federation > Entity Providers, select the check box next to the entity provider you want to delete and click Delete. 
    • AM 5.x console: navigate to: Realms > [Realm Name] > Applications > SAML > Circle of Trust Configuration > Entity Providers, select the check box next to the entity provider you want to delete and click Delete. 
    • OpenAM 13.x console: navigate to: Federation > Circle of Trust Configuration > Entity Providers, select the check box next to the entity provider you want to delete and click Delete. 
  7. Import the received metadata:
    • AM 6 and later console: navigate to Realms > [Realm Name] > Applications > Federation > Entity Providers, click Import Entity, specify the URLs of the metadata files and click OK. 
    • AM 5.x console: navigate to: Realms > [Realm Name] > Applications > SAML > Circle of Trust Configuration > Entity Providers, click Import Entity, specify the URLs of the metadata files and click OK. 
    • OpenAM 13.x console: navigate to: Federation > Circle of Trust Configuration > Entity Providers, click Import Entity, specify the URLs of the metadata files and click OK. 
  8. Verify federation is still working with the updated metadata file.

Performing key rollover for hosted IdPs (ssoadm)

Note

This example demonstrates updating the IdP's signing certificate. If you want to update the encryption certificate, you should use the -g option instead of the -b option in steps 1 and 4.

You can perform a key rollover for a hosted IdP using ssoadm as demonstrated by this example process where the existing signing certificate alias is called oldCertIdP and the new alias is called newCertIdP: 

  1. Update the hosted IdP's metadata to include the new alias (notice that you must specify both the existing and new aliases to prevent the new alias overwriting the old alias). For example:
    $ ./ssoadm update-entity-keyinfo -y http://idp.acme.com:8080/openam -u amadmin -f pwd.txt -e / -b oldCertIdP newCertIdP -c saml2
    
    Update entity keyinfo succeeded : http://idp.acme.com:8080/openam
    
  2. Export the updated metadata, for example:
    $ ./ssoadm export-entity -y http://idp.acme.com:8080/openam -u amadmin -f pwd.txt -e / -c saml2 -m IdPmetadatafile.xml -x IdPextendedfile.xml
    
    Entity descriptor was exported to file, IdPmetadatafile.xml.
    
  3. Provide the updated metadata to the remote SP. 
  4. Update the hosted IdP's metadata to remove the original alias at the point you want to rollover to the new certificate (notice you use the same command as step 1 but only specify the new alias). For example:
    $ ./ssoadm update-entity-keyinfo -y http://idp.acme.com:8080/openam -u amadmin -f pwd.txt -e / -b newCertIdP -c saml2
    
    Update entity keyinfo succeeded : http://idp.acme.com:8080/openam
  5. Export the updated metadata, for example:
    $ ./ssoadm export-entity -y http://idp.acme.com:8080/openam -u amadmin -f pwd.txt -e / -c saml2 -m IdPmetadatafile2.xml -x IdPextendedfile2.xml
    
    Entity descriptor was exported to file, IdPmetadatafile2.xml.
    
  6. Provide the updated metadata to the remote SP.

Performing key rollover for hosted SPs (ssoadm)

Note

This example demonstrates updating the SP's signing certificate. If you want to update the encryption certificate, you should use the -r option instead of the -a option in steps 1 and 4.

You can perform a key rollover for a hosted SP using ssoadm as demonstrated by this example process where the existing signing certificate alias is called oldCertSP and the new alias is called newCertSP: 

  1. Update the hosted SP's metadata to include the new alias (notice that you must specify both the existing and new aliases to prevent the new alias overwriting the old alias). For example:
    $ ./ssoadm update-entity-keyinfo -y http://sp.example.com:8080/openam -u amadmin -f pwd.txt -e / -a oldCertSP newCertSP -c saml2
    
    Update entity keyinfo succeeded : http://sp.example.com:8080/openam
    
  2. Export the updated metadata, for example:
    $ ./ssoadm export-entity -y http://sp.example.com:8080/openam -u amadmin -f pwd.txt -e / -c saml2 -m SPmetadatafile.xml -x SPextendedfile.xml
    
    Entity descriptor was exported to file, SPmetadatafile.xml.
    
  3. Provide the updated metadata to the remote IdP. 
  4. Update the hosted SP's metadata to remove the original alias at the point you want to rollover to the new certificate (notice you use the same command as step 1 but only specify the new alias). For example:
    $ ./ssoadm update-entity-keyinfo -y http://sp.example.com:8080/openam -u amadmin -f pwd.txt -e / -a newCertSP -c saml2
    
    Update entity keyinfo succeeded : http://sp.example.com:8080/openam
  5. Export the updated metadata, for example:
    $ ./ssoadm export-entity -y http://sp.example.com:8080/openam -u amadmin -f pwd.txt -e / -c saml2 -m SPmetadatafile2.xml -x SPextendedfile2.xml
    
    Entity descriptor was exported to file, SPmetadatafile2.xml.
    
  6. Provide the updated metadata to the remote IdP. 

Performing key rollover for remote IdPs (ssoadm)

You can perform a key rollover for a remote IdP using ssoadm as demonstrated by this example process: 

  1. Receive the first updated metadata file from the IdP. This file will contain both the old and new aliases.
  2. Remove the remote IdP configuration before importing the modified metadata files, for example:
    $ ./ssoadm delete-entity -y http://idp.acme.com:8080/openam -u amadmin -f pwd.txt -e / -c saml2
    
    Descriptor was deleted for entity, http://idp.acme.com:8080/openam.
    
  3. Import the received metadata, for example:
    $ ./ssoadm import-entity -u amadmin -f pwd.txt -e / -c saml2 -t cot -m ../IdPmetadatafile.xml
    
    Import file, ../IdPmetadatafile.xml
    
  4. Verify federation is still working with the updated metadata file.
  5. Receive the second updated metadata file from the IdP containing the new alias.
  6. Remove the remote IdP configuration before importing the modified metadata files, for example:
    $ ./ssoadm delete-entity -y http://idp.acme.com:8080/openam -u amadmin -f pwd.txt -e / -c saml2
    
    Descriptor was deleted for entity, http://idp.acme.com:8080/openam.
    
  7. Import the received metadata, for example:
    $ ./ssoadm import-entity -u amadmin -f pwd.txt -e / -c saml2 -t cot -m ../IdPmetadatafile2.xml
    
    Import file, ../IdPmetadatafile2.xml
  8. Verify federation is still working with the updated metadata file.
Note

To minimize downtime, you can use the ssoadm do-batch command for steps 6 and 7 to do the delete and add in quick succession. See How do I make batch changes using ssoadm in AM/OpenAM (All versions)? for further information.

Performing key rollover for remote SPs (ssoadm)

You can perform a key rollover for a remote SP using ssoadm as demonstrated by this example process: 

  1. Receive the first updated metadata file from the SP. This file will contain both the old and new aliases.
  2. Remove the remote SP configuration before importing the modified metadata files, for example:
    $ ./ssoadm delete-entity -y http://sp.example.com:8080/openam -u amadmin -f pwd.txt -e / -c saml2
    
    Descriptor was deleted for entity, http://sp.example.com:8080/openam.
    
  3. Import the received metadata, for example:
    $ ./ssoadm import-entity -u amadmin -f pwd.txt -e / -c saml2 -t cot -m ../SPmetadatafile.xml
    
    Import file, ../SPmetadatafile.xml
    
  4. Verify federation is still working with the updated metadata file.
  5. Receive the second updated metadata file from the SP containing the new alias.
  6. Remove the remote SP configuration before importing the modified metadata files, for example:
    $ ./ssoadm delete-entity -y http://sp.example.com:8080/openam -u amadmin -f pwd.txt -e / -c saml2
    
    Descriptor was deleted for entity, http://sp.example.com:8080/openam.
    
  7. Import the received metadata, for example:
    $ ./ssoadm import-entity -u amadmin -f pwd.txt -e / -c saml2 -t cot -m ../SPmetadatafile2.xml
    
    Import file, ../SPmetadatafile2.xml
  8. Verify federation is still working with the updated metadata file.
Note

To minimize downtime, you can use the ssoadm do-batch command for steps 6 and 7 to do the delete and add in quick succession. See How do I make batch changes using ssoadm in AM/OpenAM (All versions)? for further information.

See Also

How do I export and import SAML metadata in AM/OpenAM (All versions)? 

How do I renew expired certificates for a hosted IdP or SP in AM/OpenAM (All versions)?

How do I renew expired certificates for a remote IdP or SP in AM/OpenAM (All versions)?

FAQ: SAML certificate management in AM/OpenAM

SAML Federation in AM/OpenAM

SAML v2.0 Guide

Setup and Maintenance Guide › Setting Up Keys and Keystores

Reference › Command Line Tools › ssoadm

Related Training

N/A

Related Issue Tracker IDs

N/A


How do I renew expired certificates for a hosted IdP or SP in AM/OpenAM (All versions)?

The purpose of this article is to provide information on renewing expired X.509 signing certificates for a hosted IdP or SP (entity provider) for SAML2 Federation in AM/OpenAM.

Updating certificates

AM/OpenAM uses a JCEKS keystore as its default keystore as of OpenAM 13.5. The default location is: %BASE_DIR%/%SERVER_URI%/keystore.jceks; you can change this by navigating to: Configure > Server Defaults > Security > Key Store > Keystore File.

Prior to OpenAM 13.5, OpenAM stores its default signing key in a Java Keystore file located in the $HOME/openam/openam/keystore.jks; you can check the location of this keystore in the OpenAM console by navigating to: Configuration > Servers and Sites > Default Server Settings > Security > Key Store.

Note

It is recommended that you backup your keystore.jceks | keystore.jks, .keypass and .storepass files before making any changes.

  1. Delete the expired certificate from the hosted IdP or SP keystore using the following command:
    $ keytool -delete -noprompt -alias [alias] -keystore [keystore] -storepass [password]
    replacing [alias], [keystore] and [password] with appropriate values.
  2. Import the new certificate into the hosted IdP or SP keystore using the following command:
    $ keytool -v -importkeystore -srckeystore [sourcekeystore] -srcstoretype PKCS12 -srcstorepass [sourcepassword] -destkeystore [keystore] -deststoretype [type] -deststorepass [password] -alias [alias]
    
    replacing [sourcekeystore], [sourcepassword], [keystore], [type], [password] and [alias] with appropriate values. The alias must match the alias of your expired certificate.
  3. Update the X.509 certificate in the hosted IdP or SP keystore using the following ssoadm command:
    $ ./ssoadm update-entity-keyinfo -u [adminID] -f [passwordfile] -y [entityID] -b [IdPsigningalias] -g [IdPencryptionalias]
    replacing [adminID], [passwordfile], [entityID], [IdPsigningalias] and [IdPencryptionalias] with appropriate values.
  4. Restart the web application container in which AM/OpenAM runs to apply these changes.
  5. Ensure any other applicable entity providers have also been updated with the new metadata. For AM/OpenAM based entity providers, use this article for hosted entity providers and see How do I renew expired certificates for a remote IdP or SP in AM/OpenAM (All versions)? for remote entity providers. You can share updated metadata with other entity providers by exporting the metadata data to an XML file or by providing a URL as detailed in How do I export and import SAML metadata in AM/OpenAM (All versions)? 
Caution

If you have generated a self-signed certificate, it is not automatically trusted by other applications.  In order to trust the new certificate, you need to export it from your keystore file, and import it into the cacerts file for your Java installation. By default your JVM keystore will be in your JAVA_HOME/JRE/lib/security/cacerts. Detailed steps are available in Installation Guide › Securing Installations › Using Self-Signed Certificates.

See Also

How do I rollover certificates for an IdP or SP in AM (All versions) and OpenAM 13.x?

How do I change the Signing Key for Federation in OpenAM 12.x and 13.x?

How do I update the certificate alias for the signing key in the AM/OpenAM (All versions) keystore?

How do I renew expired certificates for a remote IdP or SP in AM/OpenAM (All versions)?

How do I change the metaAlias for an existing IdP or SP in AM/OpenAM (All versions)?

How do I export and import SAML metadata in AM/OpenAM (All versions)?

FAQ: SAML certificate management in AM/OpenAM

SAML v2.0 Guide

Setup and Maintenance Guide › Setting Up Keys and Keystores

Reference › Command Line Tools › ssoadm

Related Training

N/A

Related Issue Tracker IDs

N/A


How do I renew expired certificates for a remote IdP or SP in AM/OpenAM (All versions)?

The purpose of this article is to provide information on renewing expired X.509 signing certificates for a remote IdP or SP (entity provider) for SAML2 Federation in AM/OpenAM.

Updating certificates

Note

Step 1 in the following process is optional and is only needed if you have made lots of customizations to the extended metadata for the remote IdP or SP.

You can renew expired certificates as follows for a remote IdP or SP:

  1. Export the remote IdP or SP extended metadata, if required, using the following ssoadm command:
    $ ./ssoadm export-entity -u [adminID] -f [passwordfile] -e [realmname] -y [entityID] -c saml2 -x [extendedXMLfile]
    replacing [adminID], [passwordfile], [realmname], [entityID] and [extendedXMLfile] with appropriate values.
  2. Delete the remote IdP or SP using the following ssoadm command:
    $ ./ssoadm delete-entity -u [adminID] -f [passwordfile] -e [realmname] -y [entityID]
    replacing [adminID], [passwordfile], [realmname] and [entityID] with appropriate values.
  3. Import the remote IdP or SP using the following ssoadm command to re-create the entity provider:
    $ ./ssoadm import-entity -u [adminID] -f [passwordfile] -e [realmname] -t [entityCOT] -c saml2 -m [metadataXMLfile] -x [extendedXMLfile]
    replacing [adminID], [passwordfile], [realmname], [entityCOT], [metadataXMLfile] and [extendedXMLfile] with appropriate values. You only need to import the extended metadata if you exported this in step 1.​
  4. Ensure any other applicable entity providers have also been updated with the new metadata. For AM/OpenAM based entity providers, use this article for remote entity providers and see How do I renew expired certificates for a hosted IdP or SP in AM/OpenAM (All versions)? for hosted entity providers. You can share updated metadata with other entity providers by exporting the metadata data to an XML file or by providing a URL as detailed in How do I export and import SAML metadata in AM/OpenAM (All versions)?

See Also

How do I rollover certificates for an IdP or SP in AM (All versions) and OpenAM 13.x?

How do I renew expired certificates for a hosted IdP or SP in AM/OpenAM (All versions)?

How do I change the metaAlias for an existing IdP or SP in AM/OpenAM (All versions)?

How do I export and import SAML metadata in AM/OpenAM (All versions)?

SAML v2.0 Guide

Reference › Command Line Tools › ssoadm

Related Training

N/A

Related Issue Tracker IDs

OPENAM-2350 (Implement ssoadm command to update portions of standard/extended SAML metadata)


How do I change the Signing Key for Federation in OpenAM 12.x and 13.x?

The purpose of this article is to provide information on changing the Signing Key for Federation in OpenAM 12.x and 13.x. This information applies to changing SAML2 and OAuth certificates if you are using XUI.

Background Information

The default 'test' certificate alias used for SAML2 and OAuth signing keys is also used by the XUI and for REST authentication in OpenAM.

Note

If you have multiple servers in a site, you can clone the keys and certificates by exporting and re-importing to another keystore or by simply copying the keystore across. The aliases in the keystores don't have to match providing each server points to the right aliases for its own keystore.

The JKS keystore is used in OpenAM 12.x and 13.0; a new JCEKS keystore type was introduced in OpenAM 13.5, which is used by default for new OpenAM 13.5 installations. If you have upgraded to OpenAM 13.5, the JKS keystore is still used by default. See OpenAM Release Notes › What's New in OpenAM 13.5 › Smarter Security Features for further information about the JCEKS keystore.

The keystore type affects the process used to change the signing key.

OpenAM 13.x

You should follow the appropriate process according to which keystore type you are using:

OpenAM 12.x 

The procedure in the OpenAM 12 Admin Guide: To Change the Signing Key for Federation describes creating a new keystore.jks and replacing the default keystore.jks with the newly created one. This process removes the default 'test' alias and replaces it with a newly created alias. If you follow this procedure, you will not be able to log into the OpenAM console with XUI enabled or make REST calls. See Unable to login to OpenAM console 12.x and 13.x or access REST API after changing the Federation Signing Key for further information on this issue.

If you are using OpenAM 12.x, you should follow the procedure detailed in the Changing the signing key in OpenAM 12.x section instead. 

Changing the signing key in OpenAM 12.x

Note

You should ensure you have up to date backups prior to changing the signing key in case you need to revert your changes.

You can follow the procedure in the OpenAM Admin Guide with an additional step prior to restarting the web application container in which OpenAM runs.

You have two choices as to which additional step you take:

  • Update the organization authentication certificate alias to match the newly created alias.
  • Add the new certificate alias to the existing keystore rather than replacing the keystore. 

Update the organization authentication certificate alias to match the newly created alias

To change the signing key:

  1. Take a backup of your configuration data as described in How do I make a backup of configuration data in AM/OpenAM (All versions)?
  2. Follow steps 1 to 4 in the OpenAM Admin Guide: To Change the Signing Key for Federation.
  3. Update the authentication certificate alias to match the alias of the new signing key using either the OpenAM console or ssoadm. You can either do this globally or per realm:
    • Globally:
      • OpenAM console: navigate to: Configuration > Authentication > Core > Security > Organization Authentication Certificate Alias and enter the alias of the new signing key.
      • ssoadm: enter the following command:
        $ ./ssoadm set-attr-defs -s iPlanetAMAuthService -t organization -u [adminID] -f [passwordfile] -a iplanet-am-auth-key-alias=[signingkeyalias]
        replacing [adminID], [passwordfile] and [signingkeyalias] with appropriate values.
    • Realm:
      • OpenAM console: navigate to: Access Control > [Realm Name] > Authentication > All Core Settings > Security > Organization Authentication Certificate Alias and enter the alias of the new signing key.
      • ssoadm: enter the following command:
        $ ./ssoadm set-realm-svc-attrs -s iPlanetAMAuthService -e [realmname] -u [adminID] -f [passwordfile] -a iplanet-am-auth-key-alias=[signingkeyalias]
        replacing [realmname], [adminID], [passwordfile] and [signingkeyalias] with appropriate values.
  4. Continue with steps 5 to 8 in the OpenAM Admin Guide: To Change the Signing Key for Federation.

Add the new certificate alias to the existing keystore rather than replacing the keystore

To change the signing key:

  1. Take a backup of your configuration data as described in How do I make a backup of configuration data in AM/OpenAM (All versions)?
  2. Add a new key to your existing OpenAM keystore with a command such as:
    $ keytool -genkey -keyalg RSA -alias selfsigned -keystore $OPENAM_HOME/openam/keystore.jks -storepass changeit -validity 360 -keysize 2048
    Where selfsigned is the alias of the new signing key and changeit is your keystore password.
  3. Continue with steps 6 to 8 in the OpenAM Admin Guide: To Change the Signing Key for Federation.

This process will allow you to continue using the 'test' certificate alias for XUI and signed REST calls, and use a different certificate alias for federation; however, it is not recommended that you use the 'test' certificate alias in production. You should consider updating the authentication certificate alias to match the alias of the new signing key as per step 3 in the first procedure above. 

See Also

Unable to login to OpenAM console 12.x and 13.x or access REST API after changing the Federation Signing Key 

How do I update the certificate alias for the signing key in the AM/OpenAM (All versions) keystore?

FAQ: SAML certificate management in AM/OpenAM

idmdude - How to Configure OpenAM Signing Keys

Related Training

N/A

Related Issue Tracker IDs

OPENAM-6824 (Procedure To Change the Signing Key for Federation results in being locked out of XUI)

OPENAM-6003 (value for 'iplanet-am-auth-key-alias' should be checked when saving)


How do I use two different signing keys to sign SAML responses in OpenAM 11.x and 12.x?

The purpose of this article is to provide assistance if you want to use two different signing keys to sign SAML responses in OpenAM 11.x and 12.x, where the signing key to use is determined by the entity ID of the relying party. This can either be the IdP or SP.

Using two different signing keys

Note

OpenAM 13.0 supports multiple signing keys. In pre-13.0 versions of OpenAM, you can work round this by creating a second IdP or SP that is identical to the first IdP or SP apart from the signing key and entity ID.

This example process sets up two different signing keys on the IdP side, with the SP as the relying party (but you can do it the other way round if applicable):

  1. Create a second IdP that is identical to the existing IdP, apart from having a different signing key and entity ID. This new IdP should be created in the same realm as the existing one.
  2. Add this second IdP to the same circle of trust as the existing IdP.
  3. Make the SP aware of the changed metadata. If OpenAM is also your SP, you can export the metadata from the new IdP and import it to the SP using the commands detailed in How do I export and import SAML metadata in AM/OpenAM (All versions)?

See Also

How do I renew expired certificates for a hosted IdP or SP in AM/OpenAM (All versions)?

How do I renew expired certificates for a remote IdP or SP in AM/OpenAM (All versions)?

How do I change the metaAlias for an existing IdP or SP in AM/OpenAM (All versions)?

FAQ: SAML certificate management in AM/OpenAM

OpenAM Administration Guide › Managing SAML v2.0 Federation

OpenAM Reference › OpenAM Command Line Tools › ssoadm

Related Training

N/A

Related Issue Tracker IDs

OPENAM-3493 (RFE: SAML - supporting multiple keys (key rollover))


How do I enable validation checks for SAML certificates in AM/OpenAM (All versions)?

The purpose of this article is to provide information on enabling validation checks for SAML certificates (signing and CA) in AM/OpenAM. When enabled, AM/OpenAM checks certificates against the Certificate Revocation List (CRL) for every signed assertion received.

Overview

You can choose to enable validation checks for signing certificates, CA certificates or both. When enabled, AM/OpenAM checks certificates against the CRL for every signed assertion received; any issues will cause federation to completely fail with errors such as:

ERROR: FMSigProvider.verify: Signing Certificate is validated as bad.

AM/OpenAM does not validate certificates when encrypting or signing an assertion. An RFE exists for this:  OPENAM-6134 (Perform revocation check on certificate before encrypting SAML2 assertions).

Validating Certificates

You can enable validation checks for SAML certificates as follows:

  1. Enable certificate validation for signing certificates and/or CA certificates using either the console or ssoadm:
    • AM / OpenAM 13.x console: navigate to: Configure > Global Services > SAMLv2 Service Configuration and enable XML Signing Certificate Validation and/or CA Certificate Validation.
    • Pre-OpenAM 13.5 console: navigate to: Configuration > Global > SAMLv2 Service Configuration and select the Enabled option against XML Signing Certificate Validation and/or CA Certificate Validation.
    • ssoadm: enter the following command:
      $ ./ssoadm set-attr-defs -s sunFAMSAML2Configuration -t global -u [adminID] -f [passwordfile] -a SigningCertValidation=true CACertValidation=true
      replacing [adminID] and [passwordfile] with appropriate values. You can exclude one of the attributes if you do not want to set validation checks for both signing certificates and CA certificates.
  2. Set the following JVM property if your signing certificate has a CDP extension (CRL Distribution Point) to enable checking of certificates:
    -Dcom.sun.security.enableCRLDP=true
    See below for example of how to do this for the Apache Tomcat™ web container.
  3. Configure your LDAP server to store your CA certificates and CRLs.
  4. Enable caching of the certificate revocation list using either the console or ssoadm:
    • AM / OpenAM 13.x console: navigate to: Configure > Server Defaults > Security > Certificate Revocation List Caching and enter details of your LDAP server (that is storing the CA certificates and CRLs).
    • Pre-OpenAM 13.5 console: navigate to: Configuration > Servers and Sites > Default Server Settings > Security > Certificate Revocation List Caching and enter details of your LDAP server (that is storing the CA certificates and CRLs).
    • ssoadm: enter the following command:
      $ ./ssoadm update-server-cfg -s default -u [adminID] -f [passwordfile] -a [CRLProperties]
      
      replacing [adminID], [passwordfile] and [CRLProperties] with appropriate values, where [CRLProperties] consists of the attributes you want to set and corresponding values. The attributes you can specify are:
    • com.sun.identity.crl.cache.directory.host=
      com.sun.identity.crl.cache.directory.port=
      com.sun.identity.crl.cache.directory.ssl=
      com.sun.identity.crl.cache.directory.user=
      com.sun.identity.crl.cache.directory.password=
      com.sun.identity.crl.cache.directory.searchlocs=
      com.sun.identity.crl.cache.directory.searchattr=

Example using Apache Tomcat™ web container

You can set this property by specifying CATALINA_OPTS settings in the setenv.sh file (typically located in the /tomcat/bin/ directory). If this file doesn't exist, you should create it in the same directory as the catalina.sh file (also typically located in the /tomcat/bin/directory).

To set this property:

  1. Add the following line to the setenv.sh file:
    export CATALINA_OPTS="-Dcom.sun.security.enableCRLDP=true"
  2. Restart the web container.

See Also

FAQ: SAML certificate management in AM/OpenAM

Reference › Configuration Reference › SAML v2.0 Service Configuration

Reference › Configuration Reference › Deployment Configuration

Related Training

N/A

Related Issue Tracker IDs

OPENAM-6134 (Perform revocation check on certificate before encrypting SAML2 assertions)

OPENAM-7014 (Null pointer using SAML2 XML Signing Certificate Validation)


Manipulating Metadata


How do I export and import SAML metadata in AM/OpenAM (All versions)?

The purpose of this article is to provide information on exporting and importing SAML metadata in AM/OpenAM. SAML metadata is split between standard and extended metadata files in XML format. These files contain information about the IdP or SP entity provider and are required when configuring federation or sharing metadata with other entity providers. This information does not apply to WS-Federation entities.

Overview

Exporting your metadata files allows you to create a backup, which is highly recommended and these files can also be used for troubleshooting your configuration. Importing metadata files allows you to update or create entity providers.

Note

You cannot import non-standard SAML2 metadata files (such as ADFS or Microsoft Online) without making manual changes first. Additionally, you cannot import metadata files relating to WS-Federation entities.

The following options are available for importing and exporting metadata:

Note

If your metadata is signed, you must ensure AM/OpenAM trusts the signing certificate by importing it into the AM/OpenAM keystore. If AM/OpenAM does not trust this certificate, metadata imports will fail. See FAQ: SAML certificate management in AM/OpenAM (Q. Do I have to import a certificate into the keystore for XML signing or will AM/OpenAM use the certificate provided in the metadata?) for further information.

Using ssoadm (export and import)

ssoadm commands can be used to export and import SAML metadata for IdP and SP entity providers. You can export or import standard metadata files, extended metadata files or both. These example commands export and import both metadata files; you can drop either the -m or -x option if you only require one file.

Export

Use the following command for exporting metadata:

$ ./ssoadm export-entity -u [adminID] -f [passwordfile] -e [realmname] -y [entityID] -c saml2 -m [metadataXMLfile] -x [extendedXMLfile]

replacing [adminID], [passwordfile], [realmname], [entityID], [metadataXMLfile] and [extendedXMLfile] with appropriate values.

Import

Use the following command for importing metadata:

$ ./ssoadm import-entity -u [adminID] -f [passwordfile] -e [realmname] -t [entityCOT] -c saml2 -m [metadataXMLfile] -x [extendedXMLfile]

replacing [adminID], [passwordfile], [realmname], [entityCOT], [metadataXMLfile] and [extendedXMLfile] with appropriate values.

Using your browser or curl (export only)

The URL used to access standard metadata in your browser depends on whether you are accessing IdP or SP metadata.

Once you have derived the required URL, you can access the metadata directly via the URL in your browser or export it to a file using a curl command such as:

$ curl --output metadata.xml [URL]

IdP

The URL for IdP standard metadata uses the following format:

[ServerURL]/saml2/jsp/exportmetadata.jsp?entityid=[IdPentityID]&realm=/realmname

Where:

  • [ServerURL] is the full AM/OpenAM server URL, for example, http://host1.example.com:8080/openam 
  • [IdPentityID] is the name of your IdP entity provider. This may be a name or FQDN such as: http://idp.example.net:8080/openam.
  • realmname is the name of the realm in which the IdP entity provider is configured. If the IdP entity is configured in the top level realm (/), you can exclude the &realm parameter.

For these example details (with entity provider in top level realm), the URL to access your metadata would be:

http://host1.example.com:8080/openam/saml2/jsp/exportmetadata.jsp?entityid=http://idp.example.net:8080/openam

SP

The URL for SP standard metadata uses the following format:

 [ServerURL]/saml2/jsp/exportmetadata.jsp?entityid=[SPentityID]&realm=/realmname

Where:

  • [ServerURL] is the full AM/OpenAM server URL, for example, http://host1.example.com:8080/openam 
  • [SPentityID] is the name of your SP entity provider. This may be a name such as EmployeesSP or FQDN.
  • realmname is the name of the realm in which the SP entity provider is configured. If the SP entity is configured in the top level realm (/), you can exclude the &realm parameter.

For these example details (with entity provider in employees realm), the URL to access your metadata would be:

http://host1.example.com:8080/openam/saml2/jsp/exportmetadata.jsp?entityid=EmployeesSP&realm=/employees

Using the console (import only)

You can import SAML metadata via the console in order to create a new entity provider. There are two methods available:

  • Import entity:
    • AM 6 and later console: navigate to Realms > [Realm Name] > Applications > Federation > Entity Providers and click Import Entity. This allows you to import the standard metadata and optionally the extended metadata. You must import the extended metadata at the same time if it is required; it cannot be done later.
    • AM 5.x console: navigate to: Realms > [Realm Name] > Applications > SAML > Circle of Trust Configuration > Entity Providers and click Import Entity. This allows you to import the standard metadata and optionally the extended metadata. You must import the extended metadata at the same time if it is required; it cannot be done later.
    • Pre-AM 5 console: navigate to: Federation > Circle of Trust Configuration > Entity Providers and click Import Entity. This allows you to import the standard metadata and optionally the extended metadata. You must import the extended metadata at the same time if it is required; it cannot be done later.
  • Common Tasks:
    • AM / OpenAM 13.x console: navigate to: Realms > [Realm Name] > Common Tasks > Configure SAMLv2 Provider > Create Hosted ... Provider task. When you use these tasks to create an entity provider, you have the option of providing metadata as part of the creation process.
    • Pre-OpenAM 13 console: navigate to: Common Tasks > Create Hosted ... Provider task. When you use these tasks to create an entity provider, you have the option of providing metadata as part of the creation process.

See Also

How do I create a hosted IdP or SP in AM/OpenAM (All versions) using ssoadm?

How do I register a remote IdP or SP in AM/OpenAM (All versions) using ssoadm?

How do I renew expired certificates for a hosted IdP or SP in AM/OpenAM (All versions)?

How do I renew expired certificates for a remote IdP or SP in AM/OpenAM (All versions)?

How do I rollover certificates for an IdP or SP in AM (All versions) and OpenAM 13.x?

How do I change the metaAlias for an existing IdP or SP in AM/OpenAM (All versions)?

FAQ: SAML federation in AM/OpenAM

SAML Federation in AM/OpenAM

SAML v2.0 Guide

Related Training

N/A

Related Issue Tracker IDs

OPENAM-3841 (Export metadata produces XML Parsing Error after upgrade to AM11.0.1)


How do I update metadata for an IdP or SP in AM/OpenAM (All versions) using ssoadm?

The purpose of this article is to provide information on updating metadata for an IdP or SP in AM/OpenAM using ssoadm. Using ssoadm allows you to automate the entire entity provider update process, including adding attribute mapping, if required.

Updating metadata

Standard metadata is the information necessary to transmit an agreement between Identity and Service providers on how they want to set up the federation (through NameID) and where to reach the various services. As such, you should only change this for remote entities if the change has been requested by the remote entity itself. Similarly, if you make changes to the standard metadata for the hosted entity, you must communicate these changes to all the remote entities. You can make any changes required to the extended metadata as this is not part of the standard and is not shared.

You can update metadata for an IdP or SP using ssoadm as follows: 

  1. Back up the entity data in case you need to revert your changes. You can do this by exporting the IdP's or SP's standard and extended metadata files using the following ssoadm command:
    $ ./ssoadm export-entity -u [adminID] -f [passwordfile] -e [realmname] -y [entityID] -c saml2 -m [metadataXMLfile] -x [extendedXMLfile]
    replacing [adminID], [passwordfile], [realmname], [entityID], [metadataXMLfile] and [extendedXMLfile] with appropriate values. You will see the following response if this was successful:
    Entity descriptor was exported to file, [metadataXMLfile].
    Entity configuration was exported to file, [extendedXMLfile].
  2. Update your metadata files as necessary and include any additional details needed. If you want to map attributes, you can add attribute mapping to the extended metadata file using the following format:
    <Attribute name="attributeMap">
         <Value>EmailAddress=mail</Value>
         <Value>username=uid</Value>
    </Attribute>
    
    Where the first attribute listed (EmailAddress and username in this example) are the attributes used by the entity provider you are updating.
Note

If you have only changed the extended metadata file, you can include the -x option in the following delete-entity command to only delete the extended metadata rather than the entire entity provider. If you do this, you only need to import the extended metadata in the subsequent step.

  1. Delete the IdP or SP as follows, depending on which metadata files you updated:
    • extended metadata file only - you can use the following ssoadm command:
      $ ./ssoadm delete-entity -u [adminID] -f [passwordfile] -e [realmname] -y [entityID] -c saml2 -x
      replacing [adminID], [passwordfile], [realmname] and [entityID] with appropriate values. You will see the following response if this was successful:
      Configuration was deleted for entity, [entityID].
    • standard metadata file only or both -  you can use the following ssoadm command:
      $ ./ssoadm delete-entity -u [adminID] -f [passwordfile] -e [realmname] -y [entityID] -c saml2
      replacing [adminID], [passwordfile], [realmname] and [entityID] with appropriate values. You will see the following response if this was successful:
      Descriptor was deleted for entity, [entityID].
  2. Import the metadata file(s) to re-create or update the entity provider in OpenAM:
    $ ./ssoadm import-entity -u [adminID] -f [passwordfile] -e [realmname] -t [entityCOT] -c saml2 -m [metadataXMLfile] -x [extendedXMLfile]
    replacing [adminID], [passwordfile], [realmname], [entityCOT], [metadataXMLfile] and [extendedXMLfile] with appropriate values. You will see the following response if this was successful:
    Import file, [metadataXMLfile].
    Import file, [extendedXMLfile].
Note

You could script these changes to fully automate updating your entity providers. See How do I make batch changes using ssoadm in AM/OpenAM (All versions)? for further information on scripting ssoadm commands.

See Also

How do I export and import SAML metadata in AM/OpenAM (All versions)?

How do I change the metaAlias for an existing IdP or SP in AM/OpenAM (All versions)?

How do I change the hostname for a remote IdP or SP entity in AM/OpenAM (All versions)?

How do I create a hosted IdP or SP in AM/OpenAM (All versions) using ssoadm?

SAML Federation in AM/OpenAM

SAML v2.0 Guide

Reference › Command Line Tools › ssoadm

Related Training

N/A

Related Issue Tracker IDs

OPENAM-2350 (Implement ssoadm command to update portions of standard/extended SAML metadata)


How do I change the metaAlias for an existing IdP or SP in AM/OpenAM (All versions)?

The purpose of this article is to provide information on changing the metaAlias for an existing IdP or SP in AM/OpenAM. The metaAlias is used to locate the provider's entity identifier.

Changing the metaAlias

Note

The metaAlias value for an entity provider must be unique within a deployment.

You can change the metaAlias as follows:

  1. Export the IdP's or SP's standard and extended metadata files using the following ssoadm command:
    $ ./ssoadm export-entity -u [adminID] -f [passwordfile] -e [realmname] -y [entityID] -c saml2 -m [metadataXMLfile] -x [extendedXMLfile]
    replacing [adminID], [passwordfile], [realmname], [entityID], [metadataXMLfile] and [extendedXMLfile] with appropriate values.
  2. Update the metaAlias value in the extended metadata XML file to the required value. For example, change the default /sp metaAlias value to /test:
    <SPSSOConfig metaAlias="/test">
    
  3. Update the metaAlias in all URLs in both the standard and extended metadata XML files with the new value. For example, for the SingleLogoutService (HTTP-Redirect binding) in the standard metadata XML file, the URLs would now look like this:
    <singlelogoutservice binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" location="http://sp.example.net:28080/openam/SPSloRedirect/metaAlias/test" responselocation="http://sp.example.net:28080/openam/SPSloRedirect/metaAlias/test"></singlelogoutservice>
    
  4. Remove the hosted IdP or SP configuration before importing the modified metadata files. For example, if you have modified metadata for the SP, you would remove the SP configuration from the SP. You can do this using either the console or ssoadm: 
    • AM 6 and later console: navigate to Realms > [Realm Name] > Applications > Federation > Entity Providers and delete the hosted entity provider.
    • AM 5.x console: navigate to: Realms > [Realm Name] > Applications > SAML > Circle of Trust Configuration > Entity Providers and delete the hosted entity provider.
    • Pre-AM 5 console: navigate to: Federation > Circle of Trust Configuration > Entity Providers and delete the hosted entity provider.
    • ssoadm: enter the following command:
      $ ./ssoadm delete-entity -u [adminID] -f [passwordfile] -e [realmname] -y [entityID] -c saml2
      replacing [adminID], [passwordfile], [realmname] and [entityID] with appropriate values.
  5. Import the modified IdP's or SP's standard and extended metadata files into AM/OpenAM using the following ssoadm command:
    $ ./ssoadm import-entity -u [adminID] -f [passwordfile] -e [realmname] -t [entityCOT] -c saml2 -m [metadataXMLfile] -x [extendedXMLfile]
    replacing [adminID], [passwordfile], [realmname], [entityCOT], [metadataXMLfile] and [extendedXMLfile] with appropriate values.
  6. Remove the remote IdP or SP configuration. For example, if you have modified metadata for the SP, you would remove the SP configuration from the IdP. You can do this using either the console or ssoadm (assuming your IdP also uses AM/OpenAM): 
    • AM 6 and later console: navigate to Realms > [Realm Name] > Applications > Federation > Entity Providers and delete the remote entity provider.
    • AM 5.x console: navigate to: Realms > [Realm Name] > Applications > SAML > Circle of Trust Configuration > Entity Providers and delete the remote entity provider.
    • Pre-AM 5 console: navigate to: Federation > Circle of Trust Configuration > Entity Providers and delete the remote entity provider.
    • ssoadm: enter the following command:
      $ ./ssoadm delete-entity -u [adminID] -f [passwordfile] -e [realmname] -y [entityID] -c saml2
      replacing [adminID], [passwordfile], [realmname] and [entityID] with appropriate values.
  7. Re-create the remote entity provider that you just deleted. You can do this via the console:
    • AM / OpenAM 13.x console: navigate to Realms > [Realm Name] > Common Tasks > Configure SAMLv2 Provider and use the applicable Register Remote ... Provider work flow option.
    • Pre-OpenAM 13 console: navigate to: Common Tasks and use the applicable Register Remote ... Provider work flow option.

See Also

How do I change the hostname for a remote IdP or SP entity in AM/OpenAM (All versions)?

How do I renew expired certificates for a hosted IdP or SP in AM/OpenAM (All versions)?

How do I renew expired certificates for a remote IdP or SP in AM/OpenAM (All versions)?

How do I rollover certificates for an IdP or SP in AM (All versions) and OpenAM 13.x?

FAQ: SAML federation in AM/OpenAM

SAML Federation in AM/OpenAM

SAML v2.0 Guide

Related Training

N/A

Related Issue Tracker IDs

OPENAM-4501 (entity is searched in root realm instead of sub realm if 'metaAlias' has a trailing '/' ... SP-initiated SSO)

OPENAM-3841 (Export metadata produces XML Parsing Error after upgrade to AM11.0.1)


How do I change the hostname for a remote IdP or SP entity in AM/OpenAM (All versions)?

The purpose of this article is to provide information on changing the hostname for a remote IdP or SP entity in AM/OpenAM. This article assumes you have already successfully changed the hostname for AM/OpenAM; when you change the hostname for AM/OpenAM by exporting the service configuration and making changes, the hosted IdP or SP is also updated. However, if you have any corresponding remote entity providers on a different AM/OpenAM instance, you need to update them for SAML federation to continue working.

Changing the hostname for a remote IdP or SP entity

When you create a remote IdP or SP entity in AM/OpenAM, the server name is automatically used as the hostname for the entity. If you subsequently change the hostname for AM/OpenAM as described in Setup and Maintenance Guide › Maintaining an Instance › Changing Host Names, the hosted IdP or SP will also be updated, but you will need to update the hostname for any remote entities.

This example refers to the IdP entity, but you can update the SP entity in the same way. The following URLs are used in this example:

  • Original hostname - http://host1.example.com:18080/openam
  • New hostname - http://openam.new.example.com:28080/openam

You can change a remote IdP's hostname as follows:  

  1. Back up AM/OpenAM configuration as described in How do I make a backup of configuration data in AM/OpenAM (All versions)?
  2. Export the IdP's standard and extended metadata files using the following ssoadm command:
    $ ./ssoadm export-entity -u [adminID] -f [passwordfile] -e [realmname] -y [entityID] -c saml2 -m [metadataXMLfile] -x [extendedXMLfile]
    replacing [adminID], [passwordfile], [realmname], [entityID], [metadataXMLfile] and [extendedXMLfile] with appropriate values.
  3. Update all the Service location URLs in the standard metadata file by replacing the server name part of the URL with the new server name instead. For example, the ArtifactResolutionService looked like this before the change:
         <ArtifactResolutionService index="0" isDefault="true" Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP" Location="http://host1.example.com:18080/openam/ArtifactResolver/metaAlias/idp"/>
    
    and like this after the change:
         <ArtifactResolutionService index="0" isDefault="true" Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP" Location="http://openam.new.example.com:28080/openam/ArtifactResolver/metaAlias/idp"/>
    
  4. Update all the Service location URLs in the extended metadata file by replacing the server name part of the URL with the new server name instead. For example, the EntityConfig would now look like this after the change:
         <EntityConfig entityID="http://openam.new.example.com:28080/openam" hosted="false" xmlns="urn:sun:fm:SAML:2.0:entityconfig">
    
  5. Remove the remote IdP configuration before importing the modified metadata files using the following ssoadm command:
    $ ./ssoadm delete-entity -u [adminID] -f [passwordfile] -e [realmname] -y [entityID] -c saml2
    replacing [adminID], [passwordfile], [realmname] and [entityID] with appropriate values.
  6. Import the modified IdP's standard and extended metadata files into AM/OpenAM using the following ssoadm command:
    $ ./ssoadm import-entity -u [adminID] -f [passwordfile] -e [realmname] -t [entityCOT] -c saml2 -m [metadataXMLfile] -x [extendedXMLfile] 
    replacing [adminID], [passwordfile], [realmname], [entityCOT], [metadataXMLfile] and [extendedXMLfile] with appropriate values.

See Also

How do I make a backup of configuration data in AM/OpenAM (All versions)?

FAQ: Backing up AM/OpenAM

How do I change the metaAlias for an existing IdP or SP in AM/OpenAM (All versions)?

How do I update metadata for an IdP or SP in AM/OpenAM (All versions) using ssoadm?

How do I export and import SAML metadata in AM/OpenAM (All versions)?

SAML Federation in AM/OpenAM

Setup and Maintenance Guide › Maintaining an Instance › Changing Host Names

SAML v2.0 Guide

Reference › Command Line Tools › ssoadm

Related Training

N/A

Related Issue Tracker IDs

OPENAM-6908 (Allow the user to edit SAML entity Hostname through ssoadm)


Fedlets


How do I change the algorithm used to sign SAML requests in the Fedlet in AM (All versions) and OpenAM 12.0.3, 12.0.4, 13.x?

The purpose of this article is to provide information on changing the signature algorithm used to sign SAML requests in the Java® Fedlet in AM/OpenAM. By default, SAML requests are signed by rsa-sha1.

Overview

SAML v2.0 Guide › Implementing SAML v2.0 Service Providers Using the Fedlet › Enabling Signing and Encryption in a Fedlet provides information on configuring signing in the Fedlet.

Supported signature algorithms

The following signature algorithms are supported:

Signature algorithm Corresponding value to use in FederationConfig.properties file
rsa-sha1 http://www.w3.org/2000/09/xmldsig#rsa-sha1
rsa-sha256 http://www.w3.org/2001/04/xmldsig-more#rsa-sha256
rsa-sha384 http://www.w3.org/2001/04/xmldsig-more#rsa-sha384
rsa-sha512 http://www.w3.org/2001/04/xmldsig-more#rsa-sha512
dsa-sha1 http://www.w3.org/2000/09/xmldsig#dsa-sha1
ecdsa-sha1 http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha1
ecdsa-sha256 http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha256
ecdsa-sha384 http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha384
ecdsa-sha512 http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha512

Changing the signing algorithm

You can change the signing algorithm in the Fedlet as follows:

  1. Update the FederationConfig.properties file (located in the $HOME/fedlet directory) and set the following property to the required algorithm value (per the table in the Overview section):
    org.forgerock.openam.saml2.query.signature.alg.rsa=
    For example, to use the rsa-sha256 algorithm, you would set this property as follows:
    org.forgerock.openam.saml2.query.signature.alg.rsa=http://www.w3.org/2001/04/xmldsig-more#rsa-sha256
  2. Restart the web application container in which the Fedlet runs to apply these changes. 

See Also

How do I rotate AM/OpenAM (All versions) Fedlet debug logs?

Signature algorithm is not supported error when verifying a signed SAML assertion in AM/OpenAM (All versions)

FAQ: SAML federation in AM/OpenAM

SAML Federation in AM/OpenAM

SAML v2.0 Guide › Implementing SAML v2.0 Service Providers Using the Fedlet › Enabling Signing and Encryption in a Fedlet

Related Training

N/A

Related Issue Tracker IDs

OPENAM-1900 (Provide support for more XML signatures types in SAML query string verification process)


How do I use Fedlets in .NET applications in OpenAM 12.x and 13.x?

The purpose of this article is to explain how to use the Fedlet in your .NET application. You must configure the OpenAM .NET Fedlet to work with the identity provider (IdP).

Overview

Before you try the .NET Fedlet with OpenAM, create a hosted identity provider in a Circle of Trust to which you plan to add the Fedlet. You can perform these steps using the Create Hosted Identity Provider wizard accessed from Dashboard > Configure SAMLv2 Providers in the console. The .NET Fedlet demo requires a signing key for the identity provider. For evaluation, use the test certificate installed with OpenAM.

Before configuring the .NET Fedlet, prepare Microsoft® IIS 7 with ASP .NET v4. Import and configure access on Windows® to any certificates and private keys the .NET Fedlet needs. Also prepare Windows to allow the .NET Fedlet to log messages to Windows Event Log.

Note

A demo .NET Fedlet application is available for you to try. It is provided as is and the use of this demo is outside the scope of ForgeRock support; if you want more tailored advice, consider engaging Professional Services. You must raise a support ticket to request this demo application (Fedlet-aspnet.zip).

This article covers the following topics:

Fedlet support for SAML2 features

SAML2 feature Supported by .NET Fedlet?
IdP and SP-initiated Single Sign-On (HTTP Artifact) Yes
IdP and SP-initiated Single Sign-On (HTTP POST) Yes
IdP and SP-initiated Single Logout (HTTP POST) Yes
IdP and SP-initiated Single Logout (HTTP Redirect) Yes
Sign Requests and Responses Yes
Encrypt Assertion, Attribute, and NameID Elements Yes
Export SP Metadata Yes
Attribute Queries Yes
XACML Requests No
Multiple IdPs Yes
External IdP Discovery Service Yes
Bundled IdP Reader Service for Discovery No

Preparing IIS For Installing the .NET Fedlet

Microsoft Internet Information Server must be installed with ASP.NET v4 in order to support the .NET Fedlet application. The following steps describe how to set up IIS on Windows Server 2008 R2 to support the .NET Fedlet.

  1. Log on to the Windows server as Administrator.
  2. In Server Manager, add the IIS 7 role to install IIS 7. When adding the IIS 7 role, the wizard presents you with additional installation options. Under Application Development, select ASP.NET.
  3. Under Roles > Web Server (IIS) > Internet Information Services (IIS) Manager > server-name > Application Pools, change .NET Framework Version for your application pools to v4.0.

Importing Test Key Pairs on Windows

OpenAM ships with a test key pair unpacked during deployment into a Java Key Store under OpenAM's configuration directory. You can import this key pair on Windows, so that the .NET Fedlet demo can use the certificate and private key to perform signing, encryption, and logging in Windows Event Log. The following steps describe how to get the key pair imported and available to the .NET Fedlet on Windows Server 2008 R2.

See Windows documentation for instructions on using your own key pair when you plan to deploy the .NET Fedlet in production.

  1. Move the key pair from the Java Key Store to a PKCS#12 keystore.
    C:> keytool -importkeystore -srckeystore keystore.jks -destkeystore keystore.p12 -srcstoretype JKS -deststoretype PKCS12 -srcstorepass changeit -deststorepass changeit -srcalias test -destalias test -srckeypass changeit -destkeypass changeit -noprompt
    You can use the Java keytool command to perform this step on the system where OpenAM is installed if you do not have the command installed on the Windows system.
    $ keytool -importkeystore -srckeystore keystore.jks -destkeystore keystore.p12 -srcstoretype JKS -deststoretype PKCS12 -srcstorepass changeit -deststorepass changeit -srcalias test -destalias test -srckeypass changeit -destkeypass changeit -noprompt
  2. If necessary, copy the resulting keystore.p12 file to the Windows system.
  3. Open Microsoft Management Console. Select Start > Run, then enter mmc.
  4. In the console, add the Certificates snap-in for the Local Computer store.
  5. Select Certificates > Personal > More Actions > All Tasks > Import
  6. In the Certificate Import Wizard select the keystore.p12 file to import the keys. The password is changeit.
    • Also select Mark this key as exportable.
    • Accept other defaults until you click Finish.
  7. In Certificates > Personal > Certificates > test > More Actions > Properties, make sure the Friendly name is test.
  8. Certificates > Personal > Certificates > test > More Actions > All Tasks > Manage Private Keys, add access for Everyone (or at least the IIS 7 account, IUSR).

Preparing Windows For .NET Fedlet Event Logging

After importing the key pair for the .NET Fedlet, edit the registry to add the key that allows the .NET Fedlet to write to the Windows Event Log, and create an Event Log Custom View for the .NET Fedlet.

  1. Edit the Windows registry.
    1. Open the Windows registry editor. Select Start > Run, then enter regedit.
    2. Browse to HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Eventlog\Application.
    3. Add a new key named Fedlet. Right-click Application > New > Key.
    4. Close the Windows registry editor.
  2. Add the Event Log Custom View.
    1. Select Start > Administrative Tools > Event Viewer.
    2. Select Action > Create Custom View
    3. Select all Event level options.
    4. Select By source, and then in the drop-down menu, select Fedlet.
    5. Click OK to finish creating the custom view.
    When the .NET Fedlet logs messages, you can read them under Event Viewer (Local) > Custom Views > Fedlet.

Installing the .NET Fedlet as a Demo Application

Follow these steps to configure and install the .NET Fedlet demo application. These instructions are sufficient to test single sign-on and single logout. If you want to try the attribute query test, see the procedure, Trying the .NET Fedlet Attribute Query.

  1. Unpack the contents of the Fedlet-aspnet.zip file into a working directory. You must raise a support ticket to request this file if you have not already done so.
    • bin\ This folder contains the Fedlet.dll library, that you copy to your application's bin\ folder.
    • conf\ This folder contains the templates you edit to prepare your Fedlet configuration, including the identity provider and Fedlet (SP) metadata for federation. The completed configuration files belong in your application's App_Data\ folder.
    • readme.txt This file describes how to set up and configure .NET Fedlets.
    • SampleApp\ This folder contains the demo application.
  2. To ensure the .NET Fedlet can write messages to Windows Event Log, edit SampleApp\Web.config, to make sure that the certificate alias reflects the key pair installed in the Windows Local Computer Store and available to the IIS 7 application pool user. Default settings set the log level to write informational messages, and use the test key pair shipped with OpenAM.
    <appSettings>
        <add key="fedletLogLevel" value="info" />
        <add key="fedletMutualAuthCertAlias" value="test" />
    </appSettings>
    
    The key pair specified by the fedletMutualAuthCertAlias is used for SSL Mutual Certificate authentication when the certificate based authentication is required by and configured for the web container where the Identity Provider is deployed.
  3. Edit the template files in the SampleApp\App_Data\ folder based on where you deploy the Fedlet demo application, and on how your identity provider is configured.
    • Edit fedlet.cot to set cot-name to the name of the Circle of Trust, and to set sun-fm-trusted-providers to include the entity ID of the identity provider, and the entity ID of the Fedlet service provider.
    • Edit sp.xml and sp-extended.xml to configure the entity IDs, URLs, and Circle of Trust names to correspond to your sample application.

    Example files for a .NET Fedlet deployed at http://openam.example.com/fedlet and an identity provider in OpenAM deployed at http://openam.example.com:8080/openam are available below. The Circle of Trust name in the examples is cot, and both entities use the test key pair.

  4. Export the identity provider metadata from OpenAM, and copy the resulting idp.xml and idp-extended.xml metadata to the FedletSampleApp\App_Data\ folder.
    $ ./ssoadm create-metadata-templ -y "http://openam.example.com:8080/openam" -u amadmin -f -password -i /idp -m idp.xml -x idp-extended.xml -b test
    
    Hosted entity configuration was written to idp-extended.xml.
    Hosted entity descriptor was written to idp.xml.
    
  5. Register the Fedlet with OpenAM as a remote service provider using the sp.xml and sp-extended.xml metadata.
    • Before importing sp-extended.xml, make a copy called sp-extended-copy.xml and set hosted="0" in the root element of the copy.
    • Use the copy, sp-extended-copy.xml, when importing the Fedlet configuration into OpenAM. OpenAM must register the Fedlet as a remote service provider.
    $ ./ssoadm import-entity -u amadmin -f pwd.txt -t fedlet-cot -m sp.xml -x sp-extended-copy.xml
    
    Import file, sp.xml.
    Import file, sp-extended-copy.xml.
    
    You can also perform this step in the console by selecting Realms > [Realm Name] > Applications > SAML 2.0 > Entity Providers, and clicking the Import Entity button.
  6. Deploy the .NET Fedlet demo application in IIS.
    1. Add read and execute permissions for Everyone to the SampleApp folder.
    2. Add the .NET Fedlet as an application.
      • Select IIS console > server-name > Sites > Default Web Site > View Applications > Add Applications.
      • In the window to add the application, Alias is the deployment URI to the .NET Fedlet, so fedlet for /fedlet. Physical path is the file system path to the SampleApp folder.
    3. Restart IIS.
  7. Try the demo application links to run .NET Fedlet initiated single sign-on. At first try the .NET Fedlet as Administrator using Internet Explorer® or Microsoft Edge on the Windows system where you installed the Fedlet. This allows you to see more explicit error messages should any such messages appear.
    1. Access the .NET Fedlet.

    2. Try SSO with user name demo, password changeit.

      If you instead get HTTP 500.19 error status, ASP.NET did not register correctly. Register ASP.NET v4 manually as Administrator.
      PS C:\> C:\Windows\Microsoft.NET\Framework64\v4.0.30319\aspnet_regiis.exe -i
      Start installing ASP.NET (4.0.30319).
      ....
      Finished installing ASP.NET (4.0.30319).
      

Trying the .NET Fedlet Attribute Query

To try the .NET Fedlet Attribute Query test, the identity provider must be configured with the Attribute Authority (AttrAuth) type and should sign responses. The Fedlet must be configured to deal with signed and encrypted responses. Furthermore, map the attributes to request in both the identity provider and the Fedlet configurations.

  1. Add the Attribute Authority type to the hosted identity provider.
    1. On OpenAM where the identity provider is hosted, log into the console as amadmin.
    2. Under Realms > [Realm Name] > Applications > SAML 2.0 > Entity Providers, click the New button even though you plan to change the configuration rather than create a new provider.
    3. Select the protocol of the provider: SAMLv2.
    4. In the Create SAMLv2 Entity Provider page, do the following.
      • Set the Realm.
      • Set the Entity Identifier to the same entity identifier you selected in the previous screen.
      • In the Attribute Authority section, set the Meta Alias for example to /attra, and set the Signing certificate alias and Encryption certificate alias values to test (to use the test certificate).
      • Click Create to save your changes. Disregard any error messages stating that the entity already exists.
      AttrAuth now appears in the list of Types for your identity provider.
  2. Under Realms > [Realm Name] > Applications > SAML 2.0 > Entity Providers, select the identity provider's name to open the provider's configuration.
  3. Make sure attributes for the query are mapped on the Identity Provider. Under IDP > Attribute Mapper, add the following values to the Attribute Map if they are not yet present. Click Save to save your changes.
    • cn=cn
    • sn=sn
    • uid=uid
  4. As described in the procedure, Installing the .NET Fedlet as a Demo Application, export the identity provider metadata from OpenAM, and copy the resulting idp.xml and idp-extended.xml metadata to the .NET Fedlet SampleApp\App_Data\ folder.
  5. Update the .NET Fedlet configuration and metadata.
    1. To ensure the .NET Fedlet can write messages to Windows Event Log, edit SampleApp\Web.config, to make sure that the certificate alias reflects the key pair installed in the Windows Local Computer Store and available to the IIS 7 application pool user. Default settings set the log level to write informational messages, and use the test key pair shipped with OpenAM.
      <appSettings>
          <add key="fedletLogLevel" value="info" />
          <add key="fedletMutualAuthCertAlias" value="test" />
      </appSettings>
      
      The key pair specified by the fedletMutualAuthCertAlias is used for SSL Mutual Certificate authentication when the certificate based authentication is required by and configured for the web container where the Identity Provider is deployed.
    2. Edit the .NET Fedlet metadata files in SampleApp\App_Datafedlet.cotsp.xml, and sp-extended.xml to replace the following if you have not already done so.
      • Replace FEDLET_COT with the name of the Circle of Trust.
      • Replace FEDLET_ENTITY_ID with the entity identifier such as http://openam.example.com/fedlet.
      • Replace FEDLET_DEPLOY_URI with the URL to the .NET Fedlet, generally the same as the entity identifier.
      • Replace IDP_ENTITY_ID with the entity identifier of the identity provider such as http://openam.example.com:8080/openam.
    3. Set up signing and encryption in sp.xml for the .NET Fedlet. The Attribute Authority encrypts the response with the Fedlet's public key, and the Fedlet decrypts the response with its private key. You can set up both signing and encryption by adding a <KeyDescriptor> as the first element in the <SSODescriptor>, as in the following example.
      <KeyDescriptor use="signing">
            <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
              <ds:X509Data>
                <ds:X509Certificate>
      MIICQDCCAakCBEeNB0swDQYJKoZIhvcNAQEEBQAwZzELMAkGA1UEBhMCVVMxEzARBgNVBAgTCkNh
      bGlmb3JuaWExFDASBgNVBAcTC1NhbnRhIENsYXJhMQwwCgYDVQQKEwNTdW4xEDAOBgNVBAsTB09w
      ZW5TU08xDTALBgNVBAMTBHRlc3QwHhcNMDgwMTE1MTkxOTM5WhcNMTgwMTEyMTkxOTM5WjBnMQsw
      CQYDVQQGEwJVUzETMBEGA1UECBMKQ2FsaWZvcm5pYTEUMBIGA1UEBxMLU2FudGEgQ2xhcmExDDAK
      BgNVBAoTA1N1bjEQMA4GA1UECxMHT3BlblNTTzENMAsGA1UEAxMEdGVzdDCBnzANBgkqhkiG9w0B
      AQEFAAOBjQAwgYkCgYEArSQc/U75GB2AtKhbGS5piiLkmJzqEsp64rDxbMJ+xDrye0EN/q1U5Of+
      RkDsaN/igkAvV1cuXEgTL6RlafFPcUX7QxDhZBhsYF9pbwtMzi4A4su9hnxIhURebGEmxKW9qJNY
      Js0Vo5+IgjxuEWnjnnVgHTs1+mq5QYTA7E6ZyL8CAwEAATANBgkqhkiG9w0BAQQFAAOBgQB3Pw/U
      QzPKTPTYi9upbFXlrAKMwtFf2OW4yvGWWvlcwcNSZJmTJ8ARvVYOMEVNbsT4OFcfu2/PeYoAdiDA
      cGy/F2Zuj8XJJpuQRSE6PtQqBuDEHjjmOQJ0rV/r8mO1ZCtHRhpZ5zYRjhRC9eCbjx9VrFax0JDC
      /FfwWigmrW0Y0Q==
                </ds:X509Certificate>
              </ds:X509Data>
            </ds:KeyInfo>
          </KeyDescriptor>
          <KeyDescriptor use="encryption">
            <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
              <ds:X509Data>
                <ds:X509Certificate>
      MIICQDCCAakCBEeNB0swDQYJKoZIhvcNAQEEBQAwZzELMAkGA1UEBhMCVVMxEzARBgNVBAgTCkNh
      bGlmb3JuaWExFDASBgNVBAcTC1NhbnRhIENsYXJhMQwwCgYDVQQKEwNTdW4xEDAOBgNVBAsTB09w
      ZW5TU08xDTALBgNVBAMTBHRlc3QwHhcNMDgwMTE1MTkxOTM5WhcNMTgwMTEyMTkxOTM5WjBnMQsw
      CQYDVQQGEwJVUzETMBEGA1UECBMKQ2FsaWZvcm5pYTEUMBIGA1UEBxMLU2FudGEgQ2xhcmExDDAK
      BgNVBAoTA1N1bjEQMA4GA1UECxMHT3BlblNTTzENMAsGA1UEAxMEdGVzdDCBnzANBgkqhkiG9w0B
      AQEFAAOBjQAwgYkCgYEArSQc/U75GB2AtKhbGS5piiLkmJzqEsp64rDxbMJ+xDrye0EN/q1U5Of+
      RkDsaN/igkAvV1cuXEgTL6RlafFPcUX7QxDhZBhsYF9pbwtMzi4A4su9hnxIhURebGEmxKW9qJNY
      Js0Vo5+IgjxuEWnjnnVgHTs1+mq5QYTA7E6ZyL8CAwEAATANBgkqhkiG9w0BAQQFAAOBgQB3Pw/U
      QzPKTPTYi9upbFXlrAKMwtFf2OW4yvGWWvlcwcNSZJmTJ8ARvVYOMEVNbsT4OFcfu2/PeYoAdiDA
      cGy/F2Zuj8XJJpuQRSE6PtQqBuDEHjjmOQJ0rV/r8mO1ZCtHRhpZ5zYRjhRC9eCbjx9VrFax0JDC
      /FfwWigmrW0Y0Q==
                </ds:X509Certificate>
              </ds:X509Data>
            </ds:KeyInfo>
            <EncryptionMethod
              Algorithm="http://www.w3.org/2001/04/xmlenc#aes128-cbc">
              <xenc:KeySize
                xmlns:xenc="http://www.w3.org/2001/04/xmlenc#"
                >128</xenc:KeySize>
            </EncryptionMethod>
          </KeyDescriptor>
      
      For the Attribute Query feature, add a <RoleDescriptor> to the <EntityDescriptor> after the <SSODescriptor>. The <RoleDescriptor> describes the certificates that are used for signing and encryption.
      <RoleDescriptor
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
              xmlns:query="urn:oasis:names:tc:SAML:metadata:ext:query"
              xsi:type="query:AttributeQueryDescriptorType"
              protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
          <KeyDescriptor use="signing">
            <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
              <ds:X509Data>
                <ds:X509Certificate>
      MIICQDCCAakCBEeNB0swDQYJKoZIhvcNAQEEBQAwZzELMAkGA1UEBhMCVVMxEzARBgNVBAgTCkNh
      bGlmb3JuaWExFDASBgNVBAcTC1NhbnRhIENsYXJhMQwwCgYDVQQKEwNTdW4xEDAOBgNVBAsTB09w
      ZW5TU08xDTALBgNVBAMTBHRlc3QwHhcNMDgwMTE1MTkxOTM5WhcNMTgwMTEyMTkxOTM5WjBnMQsw
      CQYDVQQGEwJVUzETMBEGA1UECBMKQ2FsaWZvcm5pYTEUMBIGA1UEBxMLU2FudGEgQ2xhcmExDDAK
      BgNVBAoTA1N1bjEQMA4GA1UECxMHT3BlblNTTzENMAsGA1UEAxMEdGVzdDCBnzANBgkqhkiG9w0B
      AQEFAAOBjQAwgYkCgYEArSQc/U75GB2AtKhbGS5piiLkmJzqEsp64rDxbMJ+xDrye0EN/q1U5Of+
      RkDsaN/igkAvV1cuXEgTL6RlafFPcUX7QxDhZBhsYF9pbwtMzi4A4su9hnxIhURebGEmxKW9qJNY
      Js0Vo5+IgjxuEWnjnnVgHTs1+mq5QYTA7E6ZyL8CAwEAATANBgkqhkiG9w0BAQQFAAOBgQB3Pw/U
      QzPKTPTYi9upbFXlrAKMwtFf2OW4yvGWWvlcwcNSZJmTJ8ARvVYOMEVNbsT4OFcfu2/PeYoAdiDA
      cGy/F2Zuj8XJJpuQRSE6PtQqBuDEHjjmOQJ0rV/r8mO1ZCtHRhpZ5zYRjhRC9eCbjx9VrFax0JDC
      /FfwWigmrW0Y0Q==
                </ds:X509Certificate>
              </ds:X509Data>
            </ds:KeyInfo>
          </KeyDescriptor>
          <KeyDescriptor use="encryption">
            <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
              <ds:X509Data>
                <ds:X509Certificate>
      MIICQDCCAakCBEeNB0swDQYJKoZIhvcNAQEEBQAwZzELMAkGA1UEBhMCVVMxEzARBgNVBAgTCkNh
      bGlmb3JuaWExFDASBgNVBAcTC1NhbnRhIENsYXJhMQwwCgYDVQQKEwNTdW4xEDAOBgNVBAsTB09w
      ZW5TU08xDTALBgNVBAMTBHRlc3QwHhcNMDgwMTE1MTkxOTM5WhcNMTgwMTEyMTkxOTM5WjBnMQsw
      CQYDVQQGEwJVUzETMBEGA1UECBMKQ2FsaWZvcm5pYTEUMBIGA1UEBxMLU2FudGEgQ2xhcmExDDAK
      BgNVBAoTA1N1bjEQMA4GA1UECxMHT3BlblNTTzENMAsGA1UEAxMEdGVzdDCBnzANBgkqhkiG9w0B
      AQEFAAOBjQAwgYkCgYEArSQc/U75GB2AtKhbGS5piiLkmJzqEsp64rDxbMJ+xDrye0EN/q1U5Of+
      RkDsaN/igkAvV1cuXEgTL6RlafFPcUX7QxDhZBhsYF9pbwtMzi4A4su9hnxIhURebGEmxKW9qJNY
      Js0Vo5+IgjxuEWnjnnVgHTs1+mq5QYTA7E6ZyL8CAwEAATANBgkqhkiG9w0BAQQFAAOBgQB3Pw/U
      QzPKTPTYi9upbFXlrAKMwtFf2OW4yvGWWvlcwcNSZJmTJ8ARvVYOMEVNbsT4OFcfu2/PeYoAdiDA
      cGy/F2Zuj8XJJpuQRSE6PtQqBuDEHjjmOQJ0rV/r8mO1ZCtHRhpZ5zYRjhRC9eCbjx9VrFax0JDC
      /FfwWigmrW0Y0Q==
                </ds:X509Certificate>
              </ds:X509Data>
            </ds:KeyInfo>
            <EncryptionMethod
              Algorithm="http://www.w3.org/2001/04/xmlenc#aes128-cbc">
              <xenc:KeySize
                xmlns:xenc="http://www.w3.org/2001/04/xmlenc#"
                >128</xenc:KeySize>
            </EncryptionMethod>
          </KeyDescriptor>
        </RoleDescriptor>
      
    4. Edit sp-extended.xml for your configuration. Set the signing and encryption certificate aliases.
      <Attribute name="signingCertAlias">
        <Value>test</Value>
      </Attribute>
      <Attribute name="encryptionCertAlias">
        <Value>test</Value>
      </Attribute>
      
      Update the attribute map in to coincide with the mapped attributes on the identity provider.
      <Attribute name="attributeMap">
         <Value>cn=cn</Value>
         <Value>sn=sn</Value>
         <Value>uid=uid</Value>
      </Attribute>
      
      Add a logout URL.
      <Attribute name="appLogoutUrl">
         <Value>http://openam.example.com/fedlet/logout.aspx</Value>
      </Attribute>
      
      Add an <AttributeQueryConfig> to the <EntityDescriptor> that references the certificate aliases.
      <AttributeQueryConfig metaAlias="/attrQuery">
        <Attribute name="signingCertAlias">
          <Value>test</Value>
        </Attribute>
        <Attribute name="encryptionCertAlias">
          <Value>test</Value>
        </Attribute>
        <Attribute name="wantNameIDEncrypted">
          <Value>true</Value>
        </Attribute>
        <Attribute name="cotlist">
          <Value>cot</Value>
        </Attribute>
      </AttributeQueryConfig>
      
    5. Check your work by comparing and contrasting your configuration with the sample configuration files:
    6. In the console where the hosted identity provider is configured, navigate to Realms > [Realm Name] > Applications > SAML 2.0 > Entity Providers and delete the .NET Fedlet configuration if it exists.
    7. Make a copy of sp-extended.xml called sp-extended-copy.xml and set hosted="0" in the root element of the copy.
      • Use the copy, sp-extended-copy.xml, when importing the Fedlet configuration into OpenAM. OpenAM must register the Fedlet as a remoteservice provider.
    8. Under Realms > [Realm Name] > Applications > SAML 2.0 > Entity Providers, click the Import Entity button and import the .NET Fedlet configuration using your sp.xml and sp-extended-copy.xml metadata files.
  6. Deploy the .NET Fedlet as described in the deploy step of the procedure, Installing the .NET Fedlet as a Demo Application, making sure you restart IIS.
  7. Try the .NET Fedlet Attribute Query test. At first try the .NET Fedlet as Administrator using Internet Explorer or Microsoft Edge on the Windows system where you installed the Fedlet. This allows you to see more explicit error messages should any such messages appear.
    1. Access the .NET Fedlet.

    2. Try SSO with user name demo, password changeit.

      If you instead get HTTP 500.19 error status, ASP.NET did not register correctly. Register ASP.NET v4 manually as Administrator.
      PS C:\> C:\Windows\Microsoft.NET\Framework64\v4.0.30319\aspnet_regiis.exe -i
      Start installing ASP.NET (4.0.30319).
      ....
      Finished installing ASP.NET (4.0.30319).
      
    3. At the bottom of the web page, et the attributes in the Attribute Query page to match the mapped attributes, and then click Send.
    4. Check that you see the attribute values in the response page.

  8. Adapt the SSL/TLS protocol version used by the .NET Fedlet client to the needs of your deployment. The default setting for .NET v4 is to use either SSLv3 or TLSv1 depending on what the remote peer supports.

See Also

OpenAM Administration Guide › Managing SAML v2.0 Federation

Related Training

N/A

Related Issue Tracker IDs

N/A


How do I rotate AM/OpenAM (All versions) Fedlet debug logs?

The purpose of this article is to provide information on rotating AM/OpenAM Fedlet debug logs. Debug logs are located in the $HOME/fedlet/debug directory by default.

Rotating AM/OpenAM Fedlet debug logs

AM/OpenAM does not rotate Fedlet debug logs by default, but you can configure it to do so based on:

  • Time interval (in minutes) - for example, every 1440 minutes for once a day. The time interval specified starts when the first log message is logged to the log file.
  • Size (in MB) - for example, when the debug log reaches 2MB. The size option is available as of OpenAM 13.0. In versions prior to OpenAM 13, you should consider tools such as logadm (Solaris®) or logrotate (Linux®) if you want to rotate by size. These are third-party tools that we suggest can be used for log rotation but are not supported by ForgeRock.
Note

It is recommended that you copy the debug logs prior to clearing the contents, rather than deleting the logs as this can cause issues if a process is still holding a filehandle. Additionally, you should keep debug logging to a minimum (level: error) and only increase it when troubleshooting an issue.

To configure Fedlet debug file rotation:

  1. Copy the debugconfig.properties file (located in the /path/to/tomcat/webapps/openam/WEB-INF/classes directory) to a temporary location.
  2. Edit the properties in the debugconfig.properties file as detailed in Rotating Debug Logs to configure debug log file rotation. For example, if you want your Fedlet debug logs to rotate every 1440 minutes with a suffix of the date and time, you would set the rotation and suffix properties in this file as follows:
    org.forgerock.openam.debug.rotation=1440
    org.forgerock.openam.debug.suffix=-MM.dd.yyyy-HH.mm
    
    Alternatively, if you want your debug logs to rotate each time they reach 2MB with a suffix of the date and time, you would set the maxsize and suffix properties in this file as follows:
    org.forgerock.openam.debug.rotation.maxsize=2
    org.forgerock.openam.debug.suffix=-MM.dd.yyyy-HH.mm_ss.SSS
  3. Copy the debugconfig.properties file to the /path/to/deployed/fedlet/WEB-INF/classes directory. Alternatively, you can package the debugconfig.properties file in the appropriate Fedlet WAR file (in the /WEB-INF/classes directory) and redeploy.
  4. Restart the web application container in which the Fedlet runs to apply these configuration changes.

See Also

How do I rotate AM/OpenAM (All versions) debug logs?

How do I enable Message level debugging in AM/OpenAM (All versions) debug files?

How do I clear debug logs in AM/OpenAM (All versions)?

How do I rotate Web Policy Agents (All versions) debug and audit logs?

How do I rotate Java Policy Agents (All versions) debug and audit logs?

Setup and Maintenance Guide › Troubleshooting › Rotating Debug Logs

SAML v2.0 Guide › Implementing SAML v2.0 Service Providers Using the Fedlet › Using Fedlets in Java Web Applications

Related Training

N/A

Related Issue Tracker IDs

OPENAM-4113 (Request for OpenAM debug logs rotation based on size(in MB))

OPENAM-4644 (Log file rotation isn't respected)

OPENAM-4614 (MergeAll Option cause a desynchronisation of the log rotation)

OPENAM-6450 (Log Number of History files count is ignored)


Frequently Asked Questions


FAQ: SAML certificate management in AM/OpenAM

The purpose of this FAQ is to provide answers to commonly asked questions regarding SSL certificate management for AM/OpenAM Federation.

Frequently asked questions

Q. How do I change the signing key for SAML2?

A. The default 'test' certificate alias used for SAML2 (and OAuth) signing keys is also used by the XUI and for REST authentication. 

The procedure in the OpenAM 12 Admin Guide describes creating a new keystore.jks and replacing the default keystore.jks with the newly created one. This process removes the default 'test' alias and replaces it with a newly created alias, which will prevent you from logging into the console with XUI enabled or making REST calls as detailed in Unable to login to OpenAM console 12.x and 13.x or access REST API after changing the Federation Signing Key.

Q. Where are the SAML keys stored?

A. Assuming SAML signing has been implemented, the keypair (private/public key) for SAML encryption and signing is stored in the AM/OpenAM keystore, which differs depending on which version you are using. AM/OpenAM uses a JCEKS keystore as its default keystore as of OpenAM 13.5. The default location is: %BASE_DIR%/%SERVER_URI%/keystore.jceks; you can change this by navigating to: Configure > Server Defaults > Security > Key Store > Keystore File.

Prior to OpenAM 13.5, OpenAM stores its default signing key in a Java Keystore file located in the /$HOME/openam/openam/keystore.jks; you can check the location of this keystore in the console by navigating to: Configuration > Servers and Sites > Default Server Settings > Security > Key Store.

Q. How do I list the keys in my keystore?

A. You can list all the keys in your keystore using one of the following commands depending on your keystore format:

  • JCEKS format:
    $ keytool -list -v -keystore [keystore] -storetype JCEKS -storepass [password]
  • JKS format:
    $ keytool -list -v -keystore [keystore] -storepass [password]

replacing [keystore] with the full path and name of the keystore file, and [password] with the keystore password.

Q. Does AM/OpenAM support multiple signing keys to allow for key rollover?

A. As of OpenAM 13.0, AM/OpenAM supports multiple signing keys to allow for key rollover; this means you can cutover to a new certificate when the current one is either revoked or expires:

Note

AM/OpenAM does not check for the certificate expiration date as discussed in Q. Why isn't the SAML certificate expiration date checked?

In pre-OpenAM 13, you can work round this by creating a second IdP or SP that is identical to the first IdP or SP apart from the signing key. See How do I use two different signing keys to sign SAML responses in OpenAM 11.x and 12.x? for further information.

Resolved RFE: OPENAM-3493 (Update SAML to support multiple keys (key rollover))

Q. Can I use the same signing key for multiple IdPs?

A. Yes, you can use the same signing key with multiple hosted IdPs if required.

Q. Can I have multiple keys in the keystore used for signing so that I can have a different key for each IdP?

A. Yes you can. You then need to add the right alias and password combination to each IdP entity.

See Setup and Maintenance Guide › Setting Up Keys and Keystores and How do I change the Signing Key for Federation in OpenAM 12.x and 13.x? for further information.

Q. Do I need to create a new IdP or SP to update a certificate?

A. No, you can update the certificate for an existing IdP or SP without needing to create a new provider or circle of trust (COT). 

See How do I renew expired certificates for a hosted IdP or SP in AM/OpenAM (All versions)? and How do I renew expired certificates for a remote IdP or SP in AM/OpenAM (All versions)? for further information depending on whether your entity provider is hosted or remote.

Q. Do I have to import a certificate into the keystore for XML signing or will AM/OpenAM use the certificate provided in the MetaData?

A. It depends on what you are trying to do in the following situations:

Setting up federation

When you initially configure federation between AM/OpenAM and the entity provider, you need to import the entity provider's metadata. The metadata itself can be signed. If it is signed, you must have a way to trust it and typically this means you need to import the certificate into the keystore. However, if you have obtained the metadata from a trusted source, you can remove the Signature block from the metadata and import it without needing to import the certificate.

The Signature block in the metadata is the <Signature ... </Signature> part as shown in the following example:

<EntityDescriptor ...>
   <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">...
      ...
      <SignatureValue> ... </SignatureValue>
      ...
      <X509Certificate> ... </X509Certificate>
      ...
   </Signature>
...
</md:EntityDescriptor>

When this Signature block is present, the certificate in the <X509Certificate> tag must be trusted.

Verifying signatures

Once federation is configured, you may choose to receive signed requests from the Service Provider for example. If the metadata imported into AM/OpenAM contained a certificate, AM/OpenAM will use that certificate to verify the signature of the request meaning you do not need to import a certificate. This certificate will be in the <SPSSODescriptor> or the <IDPSSODescriptor> block, for example:

<EntityDescriptor    ... >
    <SPSSODescriptor ... >
        <KeyDescriptor use="signing">
            <KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
                <X509Data>
                    <X509Certificate> ... </X509Certificate>
                </X509Data>
     ...
    </SPSSODescriptor>
</EntityDescriptor>

If either the <SPSSODescriptor> or the <IDPSSODescriptor> block is present, AM/OpenAM will use that certificate to verify the signatures; if it is not present, you will need to import the certificate into the keystore.

Q. Why isn't the SAML certificate expiration date checked?

A. The expiration date isn't checked per the SAML specs: SAML V2.0 Metadata Interoperability Profile. In particular, refer to the Key Representation section, which states:

In the case of an X.509 certificate, there are no requirements as to the content of the certificate apart from the requirement that it contain the appropriate public key. Specifically, the certificate may be expired, not yet valid, carry critical or non-critical extensions or usage flags, and contain any subject or issuer. The use of the certificate structure is merely a matter of notational convenience to communicate a key and has no semantics in this profile apart from that. However, it is RECOMMENDED that certificates be unexpired.

An RFE exists to provide an option for checking for expiration dates: OPENAM-8973 (request for an configuration enhancement that allows the option to check for a SAML/Federation based certificate expiration date)

Q. Does AM/OpenAM validate certificates against the Certificate Revocation List (CRL)?

A. AM/OpenAM can validate certificates (both signing and CA) against the CRL, although this functionality is not enabled by default.

See How do I enable validation checks for SAML certificates in AM/OpenAM (All versions)? for information on enabling these validation checks.

When enabled, AM/OpenAM checks certificates against the CRL for every signed assertion received; any issues will cause federation to completely fail with errors such as:

ERROR: FMSigProvider.verify: Signing Certificate is validated as bad.

AM/OpenAM does not validate certificates when encrypting or signing an assertion. An RFE exists for this: OPENAM-6134 (Perform revocation check on certificate before encrypting SAML2 assertions).

Q. What signatures are supported for SAML XML signing?

A. As of OpenAM 12.0.3, the following XML signatures are supported when using query string signatures, that is, HTTP-Redirect binding:

Note

ForgeRock strongly recommends using *SHA-256 variants (rsa-sha256 or ecdsa-sha256).

Prior to OpenAM 12.0.3, only dsa-sha1 and rsa-sha1 were supported.

Using any other XML signatures will result in the following error:

ERROR: IDPSSOFederate.doSSOFederate: authn request verification failed. 
com.sun.identity.saml2.common.SAML2Exception: Signature algorithm is not supported. 

See Signature algorithm is not supported error when verifying a signed SAML assertion in AM/OpenAM (All versions) for further information.

Resolved RFE: OPENAM-1900 (Provide support for more XML signatures types in SAML query string verification process)

Q. How can I check if SAML signing has been implemented?

A. You can check in the console:

  • AM 6 and later console: navigate to Realms > [Realm Name] > Applications > Federation > Entity Providers > [Name of Provider] > Assertion Content > Signing and Encryption and checking which options have been selected.
  • AM 5.x console: navigate to: Realms > [Realm Name] > Applications > SAML > Circle of Trust Configuration > Entity Providers > [Name of Provider] > Assertion Content > Signing and Encryption and checking which options have been selected.
  • Pre-AM 5 console: navigate to: Federation > Circle of Trust Configuration > Entity Providers > [Name of Provider] > Assertion Content > Signing and Encryption and checking which options have been selected. 

Q. Can I sign anything other than the assertion?

A. Yes, you can choose which parts of the request or response are signed as follows:

  • In the SP, you can sign the following:
    • Authentication Requests
    • Assertions
    • Post Response
    • Artifact Response
    • Logout Request
    • Logout Response
    • Manage Name ID Request
    • Manage Name ID Response
  • In the IdP, you can sign the following:
    • Authentication Request
    • Artifact Resolve
    • Logout Request
    • Logout Response
    • Manage Name ID Request
    • Manage Name ID Response

 You can set these options in the console

  • AM 6 and later console: navigate to Realms > [Realm Name] > Applications > Federation > Entity Providers > [Name of Provider] > Assertion Content > Signing and Encryption.
  • AM 5.x console: navigate to: Realms > [Realm Name] > Applications > SAML > Circle of Trust Configuration > Entity Providers > [Name of Provider] > Assertion Content > Signing and Encryption.
  • Pre-AM 5 console: navigate to: Federation > Circle of Trust Configuration > Entity Providers > [Name of Provider] > Assertion Content > Signing and Encryption. 

Q. Can I use a Hardware Security Module (HSM) for signing SAML assertions?

A. Yes, you can use a HSM for signing SAML assertions, where the SAML keys are stored in a PKCS11 keystore.

See How do I configure AM/OpenAM (All versions) to use a Hardware Security Module (HSM) for signing SAML assertions? for further information.

Q. How do I use an existing CA signed certificate (in PEM format) for signing SAML requests?

A. You need to add the CA signed certificate to the AM/OpenAM keystore in order to use it for SAML signing. You can do this as follows:

  1. Convert the PEM certificate file to PKCS#12 (.p12) using the openssl third-party tool:
    $ openssl pkcs12 -export -in [saml.crt] -inkey [saml.key] -out [saml.p12] -name [alias]
    replacing [saml.crt], [saml.key], [saml.p12] and [alias] with appropriate values.
  2. Import the p12 file generated in step 1 into the AM/OpenAM keystore using the keytool command:
    $ keytool -importkeystore -deststorepass [changeit] -destkeypass [changeit] -destkeystore [AMkeystore] -srckeystore [saml.p12] -srcstoretype PKCS12 -srcstorepass [password] -alias [alias]
    replacing [changeit], [AMkeystore], [saml.p12], [password] and [alias] with appropriate values.

Q. How do I get the certificate out of the keystore in PEM format?

A. You can use the following keytool command to retrieve the certificate from the keystore in PEM format:

$ keytool -exportcert -alias [alias] -keypass [keypassword] -keystore [keystore] -storepass [storepassword] -rfc -file [keyStore.pem]

replacing [alias], [keypassword], [keystore], [storepassword] and [keyStore.pem] with appropriate values, where:

  • [keypassword] is the password used to protect the private key of the generated key pair. 
  • [keystore] is the full path and name of the keystore file.
  • [storepassword] is the keystore password.

Q. How do I convert a PEM certificate file and private key to PKCS#12 (.pfx .p12)?

A. You can use the openssl third-party tool to perform this conversion using the following command:

$ openssl pkcs12 -export -out [certificate.pfx] -inkey [privateKey.key] -in [certificate.crt] -certfile [CACert.crt]

replacing [certificate.pfx], [privateKey.key], [certificate.crt] and [CACert.crt] with appropriate values.

Q. How do I convert a PKCS#12 file (.pfx .p12) that contains a private key and certificates to PEM format?

A. You can use the openssl third-party tool to perform this conversion using the following command:

$ openssl pkcs12 -in [keyStore.pfx] -out [keyStore.pem] -nodes

replacing [keyStore.pfx] and [keyStore.pem] with appropriate values

Note

You can add -nocerts to only output the private key or add -nokeys to only output the certificates.

Q. What is the certificate alias setting under Server Defaults used for?

A. The default server certificate alias setting is used for SAML 1.x federation. This property (com.sun.identity.saml.xmlsig.certalias) is equivalent to the SAML 1.x default signing key. It can be found by navigating to: Configure > Server Defaults > Security > Key Store (AM / OpenAM 13.5) or Configuration > Servers and Sites > Default Server Settings > Security > Key Store (Pre-OpenAM 13.5).

Certificate aliases used for SAML2 federation are maintainable in the console

  • AM 6 and later console: navigate to Realms > [Realm Name] > Applications > Federation > Entity Providers > [Name of Provider] > Assertion Content > Signing and Encryption.
  • AM 5.x console: navigate to: Realms > [Realm Name] > Applications > SAML > Circle of Trust Configuration > Entity Providers > [Name of Provider] > Assertion Content > Signing and Encryption.
  • Pre-AM 5 console: navigate to: Federation > Circle of Trust Configuration > Entity Providers > [Name of Provider] > Assertion Content > Signing and Encryption. 

See Also

How do I use an IdP Proxy with SAML2 federation in AM/OpenAM (All versions)?

FAQ: SAML federation in AM/OpenAM

SAML Federation in AM/OpenAM

SAML v2.0 Guide

Setup and Maintenance Guide › Setting Up Keys and Keystores

How to Configure OpenAM Signing Keys

The Most Common OpenSSL Commands

keytool command

Related Training

ForgeRock Access Management Core Concepts (AM-400)


FAQ: SAML federation in AM/OpenAM

The purpose of this FAQ is to provide answers to commonly asked questions regarding SAML federation in AM/OpenAM.

Frequently asked questions

Q. What is metadata?

A. The metadata file is an XML document which contains information necessary to transmit an agreement between Identity and Service providers on how they want to set up the federation (through NameID) and where to reach the various services. This file contains settings such as endpoint URL's, supported bindings, identifiers and public keys.

Typically one metadata file will be generated by the service provider and sent to all identity providers they want to enable single sign-on with. Likewise, each identity provider will generate  metadata  to import into the service providers application. Once they are imported, they can be changed through the console or ssoadm. But if an element needed by the third party is modified, the third party must change its configuration accordingly. Similarly, if the third party were to change the service definition for example, you would need to delete the entity and reload it through the metadata file (you can also change it directly in the console).

See How do I update metadata for an IdP or SP in AM/OpenAM (All versions) using ssoadm? for further information on changing metadata via ssoadm.

Note

For a simplified overview of metadata specification with examples see SAML V2.0 Metadata Guide. This non-normative document provides a consolidated overview of frequently used elements and attribute based on the normative specifications.

Q. What is the difference between standard and extended metadata?

A. The standard metadata is the information detailed in the Q. What is metadata? above; that is, the configuration information required by both parties to create the federation. The information contained within this file is defined by the SAML metadata XSD and only allows a very limited set of settings to be included, hence the majority of the signing/encryption related options are stored in the extended metadata for the given entity.

The extended metadata contains further configuration settings (outside of the SAML metadata XSD) that are nothing to do with the third party and are not shared with them. This includes custom authentication context's, the majority of the signing / encryption related options, information such as the name of the COT an entity belongs to, whether a custom IdP adapter is implemented and any attribute mapping.

Caution

If you delete an entity provider, the configuration settings contained in the extended metadata will be lost; you should always back up your extended metadata file using ssoadm before you delete an entity provider. See How do I export and import SAML metadata in AM/OpenAM (All versions)? for further information.

Q. How do I share update metadata data with an entity provider?

A. When you update your metadata, you need to share it with other entity providers in the COT. You can do this by exporting it to an XML file via ssoadm or to a URL. You can then either share the URL or export it to a file via curl. See How do I export and import SAML metadata in AM/OpenAM (All versions)? for further information.

Q. Do I need to update the metadata for a hosted entity provider if I change the AM/OpenAM hostname?

A. No you do not. When you change the AM/OpenAM hostname as per Setup and Maintenance Guide › Changing Host Names, the hosted IdP or SP would be included in these changes. However, if you have any corresponding remote entity providers on a different AM/OpenAM instance, you would need to update them for SAML federation to continue working.

See How do I change the hostname for a remote IdP or SP entity in AM/OpenAM (All versions)? for further information.

Q. Can I change the metaAlias for an existing IdP or SP?

A. Yes, you can change the metaAlias for an existing IdP or SP by manually updating metadata.

See How do I change the metaAlias for an existing IdP or SP in AM/OpenAM (All versions)? for further information.

Note

The metaAlias value for an entity provider must be unique within a deployment.

Q. How do I investigate metadata issues?

A. It is very important that your metadata is correct. If there is an issue, you will see errors such as the following when creating your entity provider or importing metadata:

Unexpected element {}:[attributename]
Invalid metadata

You can increase debug logging to Message level as described in How do I enable Message level debugging in AM/OpenAM (All versions) debug files? and use the Federation and Configuration debug logs to help you find out more about the issue and correct your metadata. See How do I update metadata for an IdP or SP in AM/OpenAM (All versions) using ssoadm? for further information on updating your metadata.

If there is corruption in the XML file (such as junk or invisible characters), you will see an error like this in the Configuration debug log:

ERROR: XMLUtils.fatalError
org.xml.sax.SAXParseException; lineNumber: 1; columnNumber: 1; Content is not allowed in prolog.

This error is typically caused by either non UTF-8 encoded characters, or 'invisible characters' before the XML document type declaration (before <?xml version="1.0" encoding="UTF-8"?>) which is not allowed in xml. You can use a hex editor to check if any characters come before the declaration.

Q. What format should SAML assertions use?

A. All SAML assertions should use the format as specified by the SAML standard.

Q. What EncryptionMethod algorithms are supported for encrypting assertions in AM/OpenAM?

A. AM/OpenAM supports the following algorithms for encrypting assertions:

Using any other algorithms will result in the following error when trying to federate:

HTTP Status 400 - Error processing AuthnRequest. Unsupported data encryption algorithm.

Q. How does AM/OpenAM determine if an attribute should be added?

A. All attributes are added to the assertion if they are available to the IdP and have been configured for a specific SP or IdP federation, otherwise they are omitted. Therefore, the addition of attributes depends on the specific federation.

Q. Which binding should I use for SAML federation?

A. This depends on the following factors:

  • Technical considerations, such as: Is there a direct path of communication between the two servers or is a user-agent needed?
  • Security considerations, such as: Is exposing the full content of the response through the user-agent considered acceptable or is encryption possible?

See How do I know which binding to use for SAML2 federation in AM/OpenAM (All versions)? for further information. You should also consult SAML bindings; in particular, you should look at sections: SAML SOAP Binding, HTTP Redirect Binding, HTTP POST Binding and HTTP Artifact Binding to understand the available options.

Q. Why can I only see the SAML request XML and not the response XML?

A. When you use the HTTP-Artifact binding, the SP only receives the artifact from the browser. The artifact is then sent directly to the IdP to retrieve the assertion. This process is done without the knowledge of the browser to prevent sensitive information being exposed through the browser.

If you need to see the SAML response XML, you can do one of the following:

  • Increase debug logging on your SP or IdP to Message; this will show the response XML in the Federation log.
  • Use the HTTP-POST binding instead of the HTTP-Artifact binding; this will show the response XML in the HTTP Trace.

Q. What do the permitted AuthComparison parameter values mean?

A. The AuthComparison parameter allows you to specify a comparison method to evaluate the requested context classes or statements. This parameter can be included in the RequestedAuthnContext sent by the SP and you can set this parameter in the SPssoInit.jsp page. The permitted values are:

  • better: the authentication context statement in the assertion must be better (stronger) than any of the other authentication contexts specified.
  • exact: the authentication context statement in the assertion must exactly match at least one of the authentication contexts specified.
  • maximum: the authentication context statement in the assertion must not be stronger than any of the other authentication contexts specified.
  • minimum: the authentication context statement in the assertion must be at least as strong as one of the authentication contexts specified.

Q. How do I exclude the SPNameQualifier from the AuthnRequest?

A. You can exclude the SPNameQualifier from the AuthnRequest by writing a custom SAML2ServiceProviderAdapter and implementing preSingleSignOnRequest. Tto get you started, you would need to do something like this:

public void preSingleSignOnRequest(String hostedEntityID, String idpEntityID, String realm,
HttpServletRequest request, HttpServletResponse response, AuthnRequest authnRequest) throws SAML2Exception {
authnRequest.getNameIDPolicy().setSPNameQualifier(null);
}
Note

Writing a custom SAML2ServiceProviderAdapter is outside the scope of ForgeRock support; if you want more tailored advice, consider engaging Professional Services.

Q. Is there a limit to the number of remote IdPs I can have in a Circle of Trust (COT)?

A. No. The only potential limit is what your web application container can support; however, the impact of each remote IdP in a COT is minimal so you should be able to easily add hundreds of remote IdPs to your COT if desired.

Q. Can I use the same IdP in multiple COTs?

A. Yes, you can use the same IdP in different COTs, but you must ensure the entity ID is unique. This is true regardless of whether the COTs are in the same or different realms.

Q. Can I have an IdP and SP on the same AM/OpenAM instance?

A. No, this is not recommended. When AM/OpenAM is used for SAML federation, it creates a session specific to the entity's role, which causes one session to be overwritten with another if you have both an IdP and SP on the same AM/OpenAM instance. For example, when you authenticate to the IdP, a session is created for the IdP role; as soon as the assertion is processed by the SP, the IdP session is overwritten with the SP session.

However, you can have an IdP and SP on the same AM/OpenAM instance if you use different cookie domains for each entity, for example:

sp.example.com
idp.acme.com

Q. Can I deploy an IdP proxy on the same AM/OpenAM instance that hosts the IdP?

A. Deploying the IdP proxy and the IdP on the same AM/OpenAM instance can work in some contexts and with some constraints, however, it is recommended that you avoid such a configuration as it adds complexity and can cause unexpected problems. It is preferable to use the same physical server and install two separate AM/OpenAM instances with different DNS; this setup works well in a test environment. In a production environment, there may be other considerations around sharing resources and you may need to have two separate servers.

If you do decide to deploy an IdP proxy and IdP on the same instance, you must be aware of the following constraints:

  • The IdP must be on a different realm to the IdP proxy since you cannot have two entities with the same entityID within one realm (as that would mean they were also in the same COT).
  • The cookie domains of the IdP proxy and IdP must be different. This is because a session is created both on the IdP proxy and the IdP during federation; since both are on the same AM/OpenAM instance, they cannot use a different cookie name; the only way for AM/OpenAM to distinguish between the two sessions is if the entities are on different cookie domains. 
Note

The only way to get different cookie domains is by creating a DNS Alias / Realm Alias for the relevant realm so the domain is presented as unique within an AM/OpenAM instance. See Setup and Maintenance Guide › Configure DNS Aliases for Accessing a Realm for further information.

Q. How does the IdP Discovery Service determine which IdP to direct the user to?

A. The IdP Discovery Service uses the common domain cookie to determine where to send the user. If the common domain cookie does not exist, an error page is displayed.

To create the common domain cookie, at least one round trip must be completed with both the SP and IdP entities specified. This enables a mapping from the preferred IdP to the SP to be made (via an IdP initiated SSO request). After this, an SP initiated SSO request can be made without specifying the IdP entity ID; the value set in the common domain cookie from the first round trip will be used to redirect the user to the correct IdP.

See How do I configure IdP or SP initiated Single Sign On in AM/OpenAM (All versions)? for further information on IdP and SP initiated SSO requests.

Q. Can the integrated SAML2 authentication module derive the NameId format if it's not specified?

A. Yes, you can set the NameId format (forgerock-am-auth-saml2-name-id-format) to blank and it will be derived as follows:

  • If the IdP NameID Format list is empty: the first entry on the SP NameID Format list is used. If the SP list is also empty, then the default (urn:oasis:names:tc:SAML:2.0:nameid-format:persistent) is used.
  • If the IdP NameID Format list is not empty: the first entry on the SP NameID Format list that is also on the IdP NameID Format list is used. If the SP list is empty, then the first entry on the IdP NameID Format list is used.

See Authentication and Single Sign-On Guide › SAML2 Authentication Module Properties and  SAML v2.0 Guide › Deciding Between Integrated Mode and Standalone Mode for further information. 

Q. What login URL should I use for CDSSO with the integrated SAML2 authentication module?

A. Your login URL should just include the realm parameter per non-federated login, for example:

https://host1.example.com:443/openam/cdcservlet?realm=testrealm

You can configure the login URLs for Web and Java agents as detailed in: Web Agent User Guide › Login URL Properties and Java Agent User Guide › Login URL Properties

See SAML v2.0 Guide › Deciding Between Integrated Mode and Standalone Mode for further information on integrated mode.

Q. Can I configure federation between AM/OpenAM and Active Directory Federation Services (ADFS)?

A. Yes you can. You can either configure OpenAM or ADFS as the IdP as per your requirements. See ADFS 3 (Windows 2012 R2) and OpenAM 12 for further information on configuring this federation and correcting the metadata supplied by ADFS as it includes additional sections that are not supported by AM/OpenAM. You should remove these unsupported sections (ds: Signature, RoleDescriptor and SPSSODescriptor) leaving only the IDPSSODescriptor section.

There is an RFE to allow the metadata to be uploaded without editing it first: OPENAM-7185 (When Uploading metadata generated from ADFS v3 IDP, the user should not have to edit the metadata ).

If you want to use AM/OpenAM as an IdP proxy with ADFS as the IdP, see Configuring OpenAM IDP Proxy with ADFS and remote Service Provider for further information since the authentication request contains a scoping element, which is not accepted by ADFS.

Q. Is it possible to integrate a SP with AM/OpenAM if it does not support SAML?

A. You have the following options for integrating with AM/OpenAM if your SP does not support SAML:

Q. Why is the RelayState URL and SAML request ID the same for SAML requests generated by the AM/OpenAM fedlet?

A. AM/OpenAM fedlets store the actual RelayState URL in its memory cache. This RelayState cache is stored as a key:value pair, where key=SAML request ID and value=RelayState URL. The fedlet creates this RelayState cache when it sends the SAML request to the IdP (AM/OpenAM) with the RelayState URL as the SAML request ID. The IdP then sends back the SAML assertion with this RelayState URL, and the fedlet retrieves the actual value from its cache. 

The example below shows the SAML request, where you can see that the SAML request ID and RelayState URL have the same value:

SAMLRequest: 
<samlp:AuthnRequest xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
                    ID="s23f07afde1d08f98011a2c0e8028a6fced006c9ea"
                    Version="2.0"
                    IssueInstant="2016-02-11T19:22:53Z"
                    Destination="http://host1.sample.com:80/openam/SSORedirect/metaAlias/employees/idp"
                    ForceAuthn="false"
                    IsPassive="false"
                    ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
                    AssertionConsumerServiceURL="http://hrapp.external.net:8001/HR_App/fedletapplication"
                    >
    <saml:Issuer xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">HR_App</saml:Issuer>
</samlp:AuthnRequest>
RelayState: s23f07afde1d08f98011a2c0e8028a6fced006c9ea

See Also

FAQ: SAML certificate management in AM/OpenAM

How does AM/OpenAM (All versions) use account mapping to identify the end user from a SAML Assertion?

How do I customize the default SAML2 IdP account mapper in AM/OpenAM (All versions)?

How do I customize the default SAML2 SP account mapper in AM/OpenAM (All versions)?

How do I set up an IdP Proxy environment in AM/OpenAM (All versions)?

How do I create a hosted IdP or SP in AM/OpenAM (All versions) using ssoadm?

How do I create persistent SAML federation between two AM/OpenAM servers where user attributes match?

How do I create a persistent SAML federation between two AM/OpenAM servers where user attributes are different (and need mapping)?

What federation standards does AM/OpenAM support?

SAML Federation in AM/OpenAM

SAML v2.0 Guide

Related Training

ForgeRock Access Management Core Concepts (AM-400)


Known Issues


Federation fails with Unable to get AuthnRequest from cache, sending error response in AM/OpenAM (All versions)

The purpose of this article is to provide an overview of the causes and related solutions for the error "Unable to get AuthnRequest from cache, sending error response", when AM/OpenAM act as an IdP.

Symptoms

Federation fails when using SP initiated SSO, whereas IdP initiated SSO succeeds. Although the root cause is located on the IdP side, the IdP will send an assertion back to the SP, containing an error message. For that reason, the symptoms will appear on the SP side. If the SP is AM/OpenAM, it will fail with a HTTP 500 error and the following message:

The server encountered an internal error that prevented it from fulfilling this request.

 Other SPs may display a different type of error.

On the IdP side, you will see the following entry in the IdP Federation logs at error level:

ERROR: IDPSSOFederate.doSSOFederate: Unable to get AuthnRequest from cache, sending error response

At message level (or with a SAML Trace if HTTP-POST is used) you will see that the Response sent from the IdP to the SP has a StatusCode set to "Responder". This is a way for the IdP to let the SP know that there has been an issue and that it cannot send the assertion back:

<samlp:Status xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol">
        <samlp:StatusCode xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
                          Value="urn:oasis:names:tc:SAML:2.0:status:Responder"/>
</samlp:Status>

Recent Changes

Bookmarked the IdP Login page.

Changed the cache setting for SAML2.

Passed from IdP initiated SSO to SP initiated SSO.

Added an IdP instance.

Causes

This issue is due to the way AM/OpenAM (acting as the IdP) deals with a SP initiated SSO flow. Upon receiving the Authentication Request, AM/OpenAM keeps a reference to the request in the cache, called the ReqID. It then redirects the user for authentication; upon successful authentication, it creates the assertion and verifies that the reference to the original request exists in the cache. If it does not, it logs the error "Unable to get AuthnRequest from cache, sending error response" and sends a Responder to the SP.

In an IdP initiated SSO, there is no Authentication Request to refer to, which is why using IdP initiated SSO works correctly in this scenario.

There can be various causes for the issue:

  • Bookmarks: The user bookmarks the IdP landing page. The URL then holds a stale ReqID. When trying the same flow at a later date, the ReqID is no longer in the cache. Such a bookmark looks like this:
    http://idp.acme.com:8080/openam/XUI/#login/&realm=/&forward=true&spEntityID=http%3A%2F%2Fsp.example.com%3A8080%2Fopenam&goto=%2FSSORedirect%2FmetaAlias%2Fidp%3FReqID%3Ds20ea737f864932df1dd3bca2e3c7bd6b598baa420%26index%3Dnull%26acsURL%3Dhttp%253A%252F%252Fsp.example.com%253A8080%252Fopenam%252FConsumer%252FmetaAlias%252Fsp%26spEntityID%3Dhttp%253A%252F%252Fsp.example.com%253A8080%252Fopenam%26binding%3Durn%253Aoasis%253Anames%253Atc%253ASAML%253A2.0%253Abindings%253AHTTP-POST&AMAuthCookie=
    
  • Cache: The cache is too short. By default, the ReqID is kept in the cache for 10 minutes. If the cache has been shortened too much (such as 3 seconds), users will not be able to type in their credentials in time and federation will fail.
  • Timeout: Even with the default 10 minute cache in place, there are circumstances where a user leaves their browser open without logging in. When trying later on, federation will fail. This is in essence the same as having a short cache, however it will only happen occasionally and a retry would solve the issue.
  • Multiple IdPs exist, but stickiness is not enforced: This will cause issues, possibly intermittent, when the initial authentication request lands on one server and authentication happens on another. The IdP will not be able to find the ReqID in the cache and federation will fail. 

Solution

The solution will depend on the cause:

  • Bookmarks: Do not bookmark the IdP login page (the page containing the ReqId value). Users should bookmark the spSSOInit.jsp URL instead, for example:
    http://sp.example.com:8080/openam/saml2/jsp/spSSOInit.jsp?idpEntityID=http%3A%2F%2Fidp.acme.com%3A8080%2Fopenam&metaAlias=/sp
    
  • Cache: Make sure the cache allows enough time to complete the authentication chain. See How do I configure how long the SAML AuthnRequest remains in cache in AM/OpenAM (All versions)? for further information on changing the cache.
  • Timeout: Use the IdP initiated SSO to avoid the problem altogether as you cannot increase the cache indefinitely to capture all these instances. Alternatively you can write a custom IdP Adapter that would catch this scenario and, instead of returning an assertion, would interrupt the federation flow and redirect the user to a custom page. The custom page would explain there was an error, ask the user to try to log in again, and provide the link to the spSSOInit.jsp URL as shown in the first bullet.
  • Multiple IdPs exist, but stickiness is not enforced: You should enforce stickiness; if this is not possible, you will need to use the IdP initiated SSO.

See Also

How do I configure how long the SAML AuthnRequest remains in cache in AM/OpenAM (All versions)?

How do I configure IdP or SP initiated Single Sign On in AM/OpenAM (All versions)?

How do I redirect to a specific page after a successful IdP or SP initiated login in AM/OpenAM (All versions)?

How do I enable Message level debugging in AM/OpenAM (All versions) debug files?

Related Training

N/A

Related Issue Tracker IDs

OPENAM-1194 (Unable to get AuthnRequest error in multiserver setup


Illegal key size error when using a key encrypted with AES256 for SAML federation in AM/OpenAM (All versions)

The purpose of this article is to provide assistance if you receive an "Illegal key size" error when using a key with 256-bit AES encryption for SAML federation in AM/OpenAM. This error can occur regardless of whether AM/OpenAM is acting as the IdP or the SP.

Symptoms

One of the following errors is shown in the Federation debug log depending on whether AM/OpenAM is acting as the IdP or SP:

  • Acting as the IdP and sending the response to the SP:
    ERROR: FMEncProvider.encrypt: Failed to do the final data encryption. 
    com.sun.org.apache.xml.internal.security.encryption.XMLEncryptionException: Illegal key size or default parameters 
    Original Exception was java.security.InvalidKeyException: Illegal key size or default parameters 
       at com.sun.org.apache.xml.internal.security.encryption.XMLCipher.encryptData(XMLCipher.java:1074) 
       at com.sun.org.apache.xml.internal.security.encryption.XMLCipher.encryptData(XMLCipher.java:1012) 
       at com.sun.org.apache.xml.internal.security.encryption.XMLCipher.encryptElement(XMLCipher.java:761) 
       at com.sun.org.apache.xml.internal.security.encryption.XMLCipher.doFinal(XMLCipher.java:872) 
    
  • Acting as the SP and receiving the response from the IdP:
    org.apache.xml.security.algorithms.JCEMapper:09/10/2016 11:24:52:559 AM UTC: Thread[http-nio-10600-exec-8,5,main]: TransactionId[0f6493db-02a6-45d8-8aa9-7c0571c85d77-267]
    Request for URI http://www.w3.org/2001/04/xmlenc#aes256-cbc
    org.apache.xml.security.encryption.XMLCipher:09/10/2016 11:24:52:559 AM UTC: Thread[http-nio-10600-exec-8,5,main]: TransactionId[0f6493db-02a6-45d8-8aa9-7c0571c85d77-267]
    JCE Algorithm = AES/CBC/ISO10126Padding
    libSAML2:09/10/2016 11:24:52:559 AM UTC: Thread[http-nio-10600-exec-8,5,main]: TransactionId[0f6493db-02a6-45d8-8aa9-7c0571c85d77-267]
    ERROR: FMEncProvider.decrypt: Failed to decrypt data.
    org.apache.xml.security.encryption.XMLEncryptionException: Illegal key size
    Original Exception was java.security.InvalidKeyException: Illegal key size
       at org.apache.xml.security.encryption.XMLCipher.decryptToByteArray(XMLCipher.java:1762)
       at org.apache.xml.security.encryption.XMLCipher.decryptElement(XMLCipher.java:1618)
       at org.apache.xml.security.encryption.XMLCipher.doFinal(XMLCipher.java:932)
       at com.sun.identity.saml2.xmlenc.FMEncProvider.decrypt(FMEncProvider.java:621)
    

Recent Changes

The IdP and/or SP (whether remote or hosted) generated a signing key with 256-bit AES encryption.

Causes

Java® does not support keys with 256-bit AES encryption by default; only 128-bit AES encryption is supported. The following line in the debug log indicates that a key with 256-bit AES encryption is being used:

Request for URI http://www.w3.org/2001/04/xmlenc#aes256-cbc

Solution

This issue can be resolved by installing the Oracle® Java JCE unlimited strength jars. These jars can be downloaded from the following links depending on which Java version you are using:

You should then install these jar files in the $JAVA_HOME/jre/lib/security/ directory and restart the web application container in which AM/OpenAM runs.

See Also

Signature algorithm is not supported error when verifying a signed SAML assertion in AM/OpenAM (All versions)

FAQ: SAML certificate management in AM/OpenAM

FAQ: SAML federation in AM/OpenAM

SAML Federation in AM/OpenAM

Related Training

N/A

Related Issue Tracker IDs

OPENAM-7607 (OpenAM should implement "Metadata Profile for Algorithm Support")


Signature algorithm is not supported error when verifying a signed SAML assertion in AM/OpenAM (All versions)

The purpose of this article is to provide assistance if you receive a "com.sun.identity.saml2.common.SAML2Exception: Signature algorithm is not supported" error when attempting to verify a signed SAML assertion in AM/OpenAM if you are using the HTTP-Redirect binding.

Symptoms

The following error is shown in the Federation debug log when verifying a signed SAML assertion:

ERROR: IDPSSOFederate.doSSOFederate: authn request verification failed. 
com.sun.identity.saml2.common.SAML2Exception: Signature algorithm is not supported.
     at com.sun.identity.saml2.common.QuerySignatureUtil.verify(QuerySignatureUtil.java:310) 
     at com.sun.identity.saml2.profile.IDPSSOFederate.doSSOFederate(IDPSSOFederate.java:384) 
     at com.sun.identity.saml2.profile.IDPSSOFederate.doSSOFederate(IDPSSOFederate.java:129) 
     at jsp_servlet._saml2._jsp.__idpssofederate._jspService(__idpssofederate.java:130) 

Recent Changes

Added a new XML signature for requests.

Introduced HTTP-Redirect binding for AuthnRequest or other non-web SSO requests such as LogoutRequest.

Causes

The XML signature you used for requests (when the binding used is HTTP-Redirect) is not supported.

As of OpenAM 12.0.3, the following XML signatures are supported when using query string signatures (QuerySignatureUtil), that is, HTTP-Redirect binding:

Prior to OpenAM 12.0.3, only dsa-sha1 and rsa-sha1 were supported.

Solution

This issue can be resolved by using a supported XML signature (QuerySignatureUtil) for your requests. Requests are only signed by QuerySignatureUtil when the binding used is HTTP-Redirect. 

If you are using a pre-OpenAM 12.0.3 version, you can upgrade to OpenAM 12.0.3 or later, which supports additional XML signatures; you can download this version from BackStage.

HTTP-POST or HTTP-Artifact bindings

If you use HTTP-POST or HTTP-Artifact bindings for responses and want to control the response signing mechanism, the Global level setting should be sufficient; HTTP-Redirect binding in the web SSO profile can only be used for transferring requests, not responses. You can configure the signature algorithms for these responses in the console as follows:

  1. Navigate to:
    • AM / OpenAM 13.5 console: Configure > Global Services > Common Federation Configuration > XML signature algorithm and select the required signature.
    • Pre-OpenAM 13.5 console: Configuration > Global > Common Federation Configuration > XML signature algorithm and select the required signature.
  2. Save your changes.
  3. Restart the web application container in which AM/OpenAM runs to apply these changes. ​

See Also

FAQ: SAML certificate management in AM/OpenAM

SAML Federation in AM/OpenAM

SAML v2.0 Guide

Related Training

N/A

Related Issue Tracker IDs

OPENAM-1900 (Provide support for more XML signatures types in SAML query string verification process)


content length too large error when sending and receiving SAML requests in AM/OpenAM (All versions)

The purpose of this article is to provide assistance if you encounter a "content length too large" error when sending and receiving SAML requests in AM/OpenAM. You may also see a "HTTP Status 400 - Content length of the SOAP request is too long" message in the browser.

Symptoms

The following error is shown in the Federation debug log:

libSAML:10/11/2016 04:52:17:659 PM CET: Thread[http-8080-162,5,main] 
HttpRequest content length= 21709 
libSAML:10/11/2016 04:52:17:659 PM CET: Thread[http-8080-162,5,main] 
content length too large21709 
libSAML:10/11/2016 04:52:17:659 PM CET: Thread[http-8080-162,5,main] 
SAMLUtils.sendError: error page/saml2/jsp/saml2error.jsp 

You may also see the following message in the browser when this occurs:

HTTP Status 400 - Content length of the SOAP request is too long 

Recent Changes

N/A

Causes

The content length of the SAML request exceeds the value set for the com.sun.identity.saml.request.maxContentLength property. The default value for this property is 20480 (bytes).

Solution

This issue can be resolved by increasing the value of the com.sun.identity.saml.request.maxContentLength property to a value that is greater than the one reported in the debug log. There is not a recommended value for this property; it is there to prevent exceptionally long requests being processed and you should set it to allow the expected length of requests in your environment.

You can change this property using either the console or ssoadm:

  • AM / OpenAM 13.5 console: navigate to: Configure > Global Services > Common Federation Configuration > Maximum allowed content length and enter a new maximum content length value.
  • Pre-OpenAM 13.5 console: navigate to: Configuration > Global > Common Federation Configuration > Maximum allowed content length and enter a new maximum content length value.
  • ssoadm: enter the following command:
    $ ./ssoadm set-attr-defs -s sunFAMFederationCommon -t global -u [adminID] -f [passwordfile] -a MaxContentLength=[maxlength]
    replacing [adminID], [passwordfile] and [maxlength] with appropriate values.
Note

You must restart the web application container in which AM/OpenAM runs to apply these configuration changes.

See Also

SAML Federation in AM/OpenAM

Related Training

N/A

Related Issue Tracker IDs

N/A


SAML2 federation fails due to presence of &#13 characters in signature and certificate blocks in AM 6, 6.0.0.1, 6.0.0.2, 6.0.0.3 and 6.0.0.4

The purpose of this article is to provide assistance if SAML2 federation fails because the Service Provider (SP) cannot parse the signature or certificate generated by the Identity Provider (IdP) due to the presence of &#13 characters at the end of the lines, when AM is the IdP.

Symptoms

Federation fails when using SP initiated SSO; the SP may see references such as "Invalid SAML signature" in their logs and will not be able to parse the signature or certificate blocks.

The Federation debug log will show the signature and certificate blocks with &#13 at the end of lines, for example:

<ds:SignatureValue>
0n4tZCrMzco4uc91FvbWE+hSn6dJENYmxS8WJyEAlHjcBro3hOu07CK+rQqyTGU+OljbaUHF+zI/&#13;
Mgror3t3X+IeYcVg8PnRkmT1SXegl1wqmwZd/zg2WWXszC8W+XaQrlgIG+BNxg5j66HkDkTzegrE&#13;
...
</ds:SignatureValue>
<ds:KeyInfo>
<ds:X509Data>
<ds:X509Certificate>
CwUAA4IBAQBIRSXFrUyt1JxaJUCKidkS5FHcsTI3u3k+MMYBkQhLZB8lAomTwkqRPRx+rOvqLEW/&#13;
EwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMRkwFwYDVQQLExB3d3cuZGlnaWNlcnQuY29tMR0w&#13;
...
</ds:X509Certificate>

Recent Changes

Upgraded to, or installed AM 6, 6.0.0.1, 6.0.0.2, 6.0.0.3 or 6.0.0.4.

Causes

The xmlsec library used in these versions is 2.1.1, which has a known issue that causes line breaks to be replaced with these characters when the ignorelinebreak property is enabled. This property is enabled using either of the following JVM options:

-Dorg.apache.xml.security.ignoreLineBreaks=true
-Dcom.sun.org.apache.xml.internal.security.ignoreLineBreaks=true

If the XML parser used by the SP to process the assertion is not permissive, these characters will cause federation to fail. However, if the XML parser is permissive (as used by AM), federation will succeed; this explains why this issue will not affect you if AM is also acting as the SP. 

Solution

This issue can be resolved by upgrading to AM 6.0.0.5 or later; you can download this from BackStage.

Workaround

You can workaround this issue by upgrading the xmlsec library to version 2.1.2 on the AM acting as the IdP:

  1. Download xmlsec-2.1.2.jar from: http://central.maven.org/maven2/org/apache/santuario/xmlsec/2.1.2
  2. Navigate to the /path/to/tomcat/webapps/openam/WEB-INF/lib directory and:
    1. Copy the downloaded xmlsec-2.1.2.jar to this location.
    2. Rename xmlsec-2.1.1.jar to avoid any conflicts (for example, change it to xmlsec-2.1.1.jar.old).
  3. Edit the setenv.sh file (typically located in the /tomcat/bin/ directory) to add the following JAVA_OPTS:
    JAVA_OPTS='-Dorg.apache.xml.security.ignoreLineBreaks=true'
  4. Restart the web application container in which AM runs to apply these changes.

See Also

FAQ: SAML certificate management in AM/OpenAM

SAML Federation in AM/OpenAM

SAML v2.0 Guide

Related Training

N/A

Related Issue Tracker IDs

OPENAM-13577 (xmlsec 2.1.1.jar used in AM6 have issues when linebreaks enabled)


SSO fails with Login failed with unknown reason in AM/OpenAM (All versions)

The purpose of this article is to provide assistance if you encounter "Login failed with unknown reason" when Single Sign On (SSO) fails and AM/OpenAM is set up for SAML2 federation. You will also notice "Plug-in org.forgerock.openam.idrepo.ldap.DJLDAPv3Repo encountered a ldap exception. ldap errorcode=95" in your logs.

Symptoms

The following error is shown in the Federation debug log when SSO fails:

libSAML2:06/21/2018 11:36:03:814 AM UTC: Thread[http-nio-10600-exec-5,5,main]: TransactionId[df44988f-eda9-46fa-b356-b72f2945cfcb-22742]
ERROR: spAssertionConsumer.jsp: SSO failed.
com.sun.identity.saml2.common.SAML2Exception: Login failed with unknown reason.
   at com.sun.identity.saml2.profile.SPACSUtils.processResponse(SPACSUtils.java:1279)
   at org.apache.jsp.saml2.jsp.spAssertionConsumer_jsp._jspService(spAssertionConsumer_jsp.java:317)
   at org.apache.jasper.runtime.HttpJspBase.service(HttpJspBase.java:70)
   at javax.servlet.http.HttpServlet.service(HttpServlet.java:729)
   at org.apache.jasper.servlet.JspServletWrapper.service(JspServletWrapper.java:431)
   at org.apache.jasper.servlet.JspServlet.serviceJspFile(JspServlet.java:396)
   at org.apache.jasper.servlet.JspServlet.service(JspServlet.java:340)

The corresponding error is shown in the Authentication debug log when this happens:

amAccountLockout:06/21/2018 11:36:03:814 AM UTC: Thread[http-nio-10600-exec-2,5,main]: TransactionId[df44988f-eda9-46fa-b356-b72f2945cfcb-22742]
ERROR: Error inactivating user account
Message:Plug-in org.forgerock.openam.idrepo.ldap.DJLDAPv3Repo encountered a ldap exception.  ldap errorcode=95

   at org.forgerock.openam.idrepo.ldap.DJLDAPv3Repo.newIdRepoException(DJLDAPv3Repo.java:2518)
   at org.forgerock.openam.idrepo.ldap.DJLDAPv3Repo.getDN(DJLDAPv3Repo.java:2349)
   at org.forgerock.openam.idrepo.ldap.DJLDAPv3Repo.getDN(DJLDAPv3Repo.java:2309)
   at org.forgerock.openam.idrepo.ldap.DJLDAPv3Repo.getAttributes(DJLDAPv3Repo.java:782)
   at org.forgerock.openam.idrepo.ldap.DJLDAPv3Repo.getAttributes(DJLDAPv3Repo.java:731)
   at com.sun.identity.idm.server.IdServicesImpl.getAttributes(IdServicesImpl.java:676)
   at com.sun.identity.idm.server.IdCachedServicesImpl.getAttributes(IdCachedServicesImpl.java:384)
   at com.sun.identity.idm.AMIdentity.getAttribute(AMIdentity.java:416)
   at com.sun.identity.common.ISAccountLockout.isAccountLocked(ISAccountLockout.java:640)
   at com.sun.identity.authentication.service.AMAccountLockout.isAccountLocked(AMAccountLockout.java:323)
   at com.sun.identity.authentication.service.LoginState.isAccountLocked(LoginState.java:3945)
   at com.sun.identity.authentication.service.LoginState.searchUserProfile(LoginState.java:2560)
   at com.sun.identity.authentication.service.AMLoginContext.runLogin(AMLoginContext.java:589)
   at com.sun.identity.authentication.server.AuthContextLocal.submitRequirements(AuthContextLocal.java:617)
   at com.sun.identity.authentication.AuthContext.submitRequirements(AuthContext.java:1232)
   at com.sun.identity.authentication.AuthContext.submitRequirements(AuthContext.java:1218)
   at com.sun.identity.plugin.session.impl.FMSessionProvider.createSession(FMSessionProvider.java:250)
   at com.sun.identity.saml2.profile.SPACSUtils.processResponse(SPACSUtils.java:1258)

The same error is seen if you select the affected user via the Identities page (previously the Subjects tab) in the console:

Plug-in org.forgerock.openam.idrepo.ldap.DJLDAPv3Repo encountered a ldap exception. ldap errorcode=95

Recent Changes

N/A

Causes

The ldap errorcode=95 signifies that multiple matching entries exist. From Reference › LDAP Result Codes:

Unexpected Results Returned

The client-side result code that the requested single entry search operation or read operation failed because the Directory Server returned multiple matching entries (or search references) when only a single matching entry was expected. This is for client-side use only and should never be transferred over protocol.

This use case is typically the result of naming conflicts that can not be resolved automatically by replication. This situation commonly occurs when you have duplicate user entries sharing the same DN, which can be caused by concurrent updates to different user stores or replication conflicts.

Solution

Naming conflicts that can not be automatically resolved by replication can be identified by entries containing a DN addition in the form entryuuid=entryUUID-value+original-RDN,original-parent-DN. You can use ldapsearch to find conflicting entries and then resolve them manually as illustrated in Administration Guide › Resolving Replication Conflicts

See How do I find replication conflicts in DS/OpenDJ (All versions)? and How do I troubleshoot replication issues in DS/OpenDJ (All versions)? for further information on troubleshooting and resolving replication conflicts.

See Also

Data stores in AM/OpenAM

Replication in DS/OpenDJ

entryUUID Operational Attribute

Related Training

N/A

Related Issue Tracker IDs

OPENAM-13169 ( group names having the same CN but different full Distinguished Name Path)


Dynamic user profile creation fails with The password value for attribute userPassword was found to be unacceptable error in AM (All versions) and OpenAM 13.x

The purpose of this article is to provide assistance if dynamic user profile creation fails with "an ldap exception 19: The password value for attribute userPassword was found to be unacceptable" or "The password did not meet the password policy requirements" error. This issue also occurs if AM/OpenAM is acting as the Service Provider (SP) and auto-federation is configured to use dynamic account creation; you will see "SPACSUtils.processResponse : error code=-1 com.sun.identity.plugin.session.SessionException: Login failed with unknown reason" error as well in this scenario.

Symptoms

User profiles are not created as expected after successful authentication.

An error similar to one of the following is shown in the Authentication debug logs when dynamic user profile creation fails:

  • The password value for attribute userPassword was found to be unacceptable:
    ERROR: Cannot create user profile for: new_user
    amAuth:05/06/2018 11:31:22:288 PM BST: Thread[default task-1,5,main]: TransactionId[780c49b3-8b87-4eb4-9407-cc8fa553843b-2411231]
    Stack trace: 
    Message:Plug-in org.forgerock.openam.idrepo.ldap.DJLDAPv3Repo encountered an ldap exception 19: The password value for attribute userPassword was found to be unacceptable: The provided password did not contain <details of password policy>
       at org.forgerock.openam.idrepo.ldap.DJLDAPv3Repo.handleErrorResult(DJLDAPv3Repo.java:2508)
       at org.forgerock.openam.idrepo.ldap.DJLDAPv3Repo.create(DJLDAPv3Repo.java:688)
       at com.sun.identity.idm.server.IdServicesImpl.create(IdServicesImpl.java:427)
       at com.sun.identity.idm.AMIdentityRepository.createIdentity(AMIdentityRepository.java:463)
       at com.sun.identity.authentication.service.LoginState.createUserIdentity(LoginState.java:5448)
       at com.sun.identity.authentication.service.LoginState.createUserProfile(LoginState.java:1925)
       at com.sun.identity.authentication.service.LoginState.getCreateUserProfile(LoginState.java:2553)
       at com.sun.identity.authentication.service.LoginState.searchUserProfile(LoginState.java:2394)
       at com.sun.identity.authentication.service.AMLoginContext.runLogin(AMLoginContext.java:553)
       at com.sun.identity.authentication.server.AuthContextLocal.submitRequirements(AuthContextLocal.java:586)
       at com.sun.identity.authentication.AuthContext.submitRequirements(AuthContext.java:1235)
       at com.sun.identity.authentication.AuthContext.submitRequirements(AuthContext.java:1221)
    
  • The password did not meet the password policy requirements:
    amAuth:05/06/2018 11:31:22:288 PM BST: Thread[http-nio-8081-exec-1,5,main]: TransactionId[177135ec-ef6e-455f-a2bf-ed4f46a31ae6-1692]
    Stack trace: 
    Message:The password did not meet the password policy requirements.
       at org.forgerock.openam.idrepo.ldap.DJLDAPv3Repo.handleErrorResult(DJLDAPv3Repo.java:2485)
       at org.forgerock.openam.idrepo.ldap.DJLDAPv3Repo.create(DJLDAPv3Repo.java:681)
       at com.sun.identity.idm.server.IdServicesImpl.create(IdServicesImpl.java:427)
       at com.sun.identity.idm.AMIdentityRepository.createIdentity(AMIdentityRepository.java:462)
       at com.sun.identity.authentication.AuthContext.submitRequirements(AuthContext.java:1218)
       at com.sun.identity.plugin.session.impl.FMSessionProvider.createSession(FMSessionProvider.java:247)
    

If AM/OpenAM is acting as the SP, federation will fail and the user is returned to the login page after attempting to federate.

The following errors are shown in the Federation debug log when this happens: 

libSAML2:05/06/2018 11:31:22:292 PM EDT: Thread[default task-28,5,main]: TransactionId[f9aee006-bdf8-45df-bae5-b3ff46f54607-6629766]
SPACSUtils.processResponse : error code=-1
com.sun.identity.plugin.session.SessionException: Login failed with unknown reason.
   at com.sun.identity.plugin.session.impl.FMSessionProvider.createSession(FMSessionProvider.java:275)
   at com.sun.identity.saml2.profile.SPACSUtils.processResponse(SPACSUtils.java:1220)
   at org.apache.jsp.saml2.jsp.spAssertionConsumer_jsp._jspService(spAssertionConsumer_jsp.java:317)
   at org.apache.jasper.runtime.HttpJspBase.service(HttpJspBase.java:70)
   at javax.servlet.http.HttpServlet.service(HttpServlet.java:790)
libSAML2:05/06/2018 11:31:22:293 PM EDT: Thread[default task-1,5,main]: TransactionId[780c49b3-8b87-4eb4-9407-cc8fa553843b-2411231]
ERROR: spAssertionConsumer.jsp: SSO failed. 
com.sun.identity.saml2.common.SAML2Exception: Login failed with unknown reason.
   at com.sun.identity.saml2.profile.SPACSUtils.processResponse(SPACSUtils.java:1241)
   at org.apache.jsp.saml2.jsp.spAssertionConsumer_jsp._jspService(spAssertionConsumer_jsp.java:317)
   at org.apache.jasper.runtime.HttpJspBase.service(HttpJspBase.java:70)
   at javax.servlet.http.HttpServlet.service(HttpServlet.java:790)

Recent Changes

Configured dynamic user profile creation.

Configured password policies in DS/OpenDJ.

Causes

AM/OpenAM generates passwords for dynamically created user profiles; these are not configurable and do not adhere to any password policies configured in DS/OpenDJ. You will see this issue when the password policy in DS/OpenDJ requires a different format to the one used by AM/OpenAM when it generates passwords.

Solution

You can workaround this issue by disabling the DS/OpenDJ password policy validation for administrators, which allows AM/OpenAM to create passwords during dynamic user profile creation.

You can disable password policy validation using dsconfig, for example:

$ ./dsconfig set-password-policy-prop --policy-name "Default Password Policy" --set skip-validation-for-administrators:true --no-prompt

See Also

How does AM/OpenAM (All versions) use account mapping to identify the end user from a SAML Assertion?

How do I configure the SAML2 Authentication module for Auto Federation in AM (All versions) and OpenAM 13.x?

Authentication and Single Sign-On Guide › User Profile

SAML v2.0 Guide › Configuring How Remote Accounts Map To Local Accounts

Reference › dsconfig

Related Training

N/A

Related Issue Tracker IDs

OPENAM-11521 (OpenAM should not generate a password when using auto federation and dynamic profile creation)


SAML redirect is ignored when doing an IdP or SP initiated SSO with WDSSO/Kerberos authentication in OpenAM 13.0 and 13.5

The purpose of this article is to provide assistance if SAML redirection is ignored when doing an IdP or SP initiated SSO in OpenAM 13.0 and 13.5. This issue occurs when you are using a realm DNS alias for federation and that Realm is setup for Windows Desktop SSO/Kerberos authentication.

Symptoms

XUI

If you are using the XUI, you will observe the following behavior after successfully authenticating with the WDSSO authentication module:

  • You are redirected to the default SuccessURL if one has been set up for the WDSSO authentication module, OR
  • You are redirected to OpenAM and see the following message in the browser:
    You have already logged in. Do you want to log out and then login to a different organization?

Expected behavior: you are redirected to the IdP or SP depending on your setup.

Classic UI

If you are using the Classic UI, you will see the following message in the browser:

An internal authentication error has occurred. Contact your system administrator.

The following error is shown in the Authentication debug log when this happens:

ERROR: LoginViewBean.forwardTo(): There was an Exception doing the forward/redirect 
org.apache.jasper.JasperException: java.lang.ClassCastException: [Ljava.lang.String; cannot be cast to java.lang.String 
   at org.apache.jasper.servlet.JspServletWrapper.handleJspException(JspServletWrapper.java:555) 
   at org.apache.jasper.servlet.JspServletWrapper.service(JspServletWrapper.java:476) 
   at org.apache.jasper.servlet.JspServlet.serviceJspFile(JspServlet.java:396) 
   at org.apache.jasper.servlet.JspServlet.service(JspServlet.java:340) 
   at javax.servlet.http.HttpServlet.service(HttpServlet.java:729) 
   at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:291) 
   at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:206) 
   at org.apache.tomcat.websocket.server.WsFilter.doFilter(WsFilter.java:52) 
...
Caused by: java.lang.ClassCastException: [Ljava.lang.String; cannot be cast to java.lang.String 
   at com.sun.identity.saml2.common.SAML2Utils.getParameter(SAML2Utils.java:1370) 
   at com.sun.identity.saml2.common.SAML2Utils.getRealm(SAML2Utils.java:1356) 
   at org.apache.jsp.saml2.jsp.idpSSOFederate_jsp._jspService(idpSSOFederate_jsp.java:131) 
   at org.apache.jasper.runtime.HttpJspBase.service(HttpJspBase.java:70) 
   at javax.servlet.http.HttpServlet.service(HttpServlet.java:729) 
   at org.apache.jasper.servlet.JspServletWrapper.service(JspServletWrapper.java:438) 
... 72 more

Recent Changes

Upgraded to, or installed OpenAM 13.0 or 13.5.

Made changes to your configuration so that you now have the combination of using a realm DNS alias for federation purposes and have the WDSSO authentication module configured in that realm for authentication.

Causes

The realm context is lost in the process when the realm DNS alias is used, which prevents you being correctly redirected to the IdP or SP as expected. 

Solution

This issue can be resolved by upgrading to OpenAM 13.5.1 or later; you can download this from BackStage.

Workaround

Alternatively, the following options are available to resolve this issue:

  • You can update your configuration so that you use the OpenAM DNS URL for federation rather than the realm DNS alias.
  • You can use an alternative authentication module.

See Also

N/A

Related Training

N/A

Related Issue Tracker IDs

OPENAM-8351 (SAML2 JSP pages making use of the SAML2Auditor are calling the SAML2Utils.getRealm with an incorrect Map structure)

OPENAM-8971 (currentGoto : null is received in XUI when a realm dns is being used for Federation and authentication is done via wdsso/kerberos auth module)


There was an Exception doing the forward/redirect error and SAML2 authentication fails when redirecting with a SAML2 JSP page in OpenAM 13.0

The purpose of this article is to provide assistance if you see the following "ERROR: LoginViewBean.forwardTo(): There was an Exception doing the forward/redirect org.apache.jasper.JasperException: java.lang.ClassCastException: [Ljava.lang.String; cannot be cast to java.lang.String" and SAML2 authentication fails when redirecting with a SAML2 JSP page (such as a SP initiated SSO) in OpenAM 13.0. This issue only affects redirects that include the realm or where you are using a realm DNS alias.

Symptoms

The following error is shown in the browser when SAML authentication fails:

An internal authentication error has occurred.

The following error is shown in the Authentication debug log:

amLoginViewBean:10/06/2016 14:57:01:782 PM GMT: Thread[catalina-exec-11,5,main]: TransactionId[b390ea18-c60b-4e13-acc0-a81aeb7e809d-51] 
ERROR: LoginViewBean.forwardTo(): There was an Exception doing the forward/redirect
org.apache.jasper.JasperException: java.lang.ClassCastException: [Ljava.lang.String; cannot be cast to java.lang.String 
   at org.apache.jasper.servlet.JspServletWrapper.handleJspException(JspServletWrapper.java:555) 
   at org.apache.jasper.servlet.JspServletWrapper.service(JspServletWrapper.java:476) 
   at org.apache.jasper.servlet.JspServlet.serviceJspFile(JspServlet.java:396) 
   at org.apache.jasper.servlet.JspServlet.service(JspServlet.java:340) 
   at javax.servlet.http.HttpServlet.service(HttpServlet.java:729) 
   at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:291) 
   at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:206)
... 
Caused by: java.lang.ClassCastException: [Ljava.lang.String; cannot be cast to java.lang.String 

Recent Changes

Upgraded to, or installed OpenAM 13.0.

Causes

Recent changes to the SAML2 JSP pages that included a new call to retrieve the realm caused a mismatch in what was sent versus what was expected. These changes caused authentication to fail in this way when redirecting with a SAML2 JSP page that included a realm parameter or a realm DNS alias is used.

Solution

This issue can be resolved by upgrading to OpenAM 13.5 or later; you can download this version from BackStage.

See Also

N/A

Related Training

N/A

Related Issue Tracker IDs

OPENAM-8351 (SAML2 JSP pages making use of the SAML2Auditor are calling the SAML2Utils.getRealm with an incorrect Map structure)

OPENAM-8192 (spSSOInit with IDP proxy gives null pointer exception)

OPENAM-8971 (currentGoto : null is received in XUI when a realm dns is being used for Federation and authentication is done via wdsso/kerberos auth module)


test key provided with AM 5.x and OpenAM 12.x, 13.x has expired

The purpose of this article is to provide assistance if you encounter an issue because the test key provided with AM/OpenAM has expired. The default 'test' certificate alias used for SAML2 and OAuth signing keys is also used by the XUI and for REST authentication in AM/OpenAM. The test key expired on January 12, 2018.

Symptoms

The test key has expired.

Recent Changes

N/A

Causes

The test key provided with AM/OpenAM expired on January 12, 2018.

Note

The test key should not be used in production; ​​​​​it is only provided for testing purposes. See Installation Guide › Securing Communications for further information.

Solution

Change the test key as described in the documentation appropriate to your version:

See Also

N/A

Related Training

N/A

Related Issue Tracker IDs

N/A


Unable to login to OpenAM console 12.x and 13.x or access REST API after changing the Federation Signing Key

The purpose of this article is to provide assistance if you cannot log into the OpenAM console 12.x and 13.x (XUI) or access the REST API after changing the Signing Key or certificate alias for SAML2 or OAuth, and you receive a code 500 "Internal Server Error" "The server encountered an unexpected condition which prevented it from fulfilling the request".

Symptoms

When attempting to access the OpenAM console or the REST API, the following error is seen:

code: 500 
reason: "Internal Server Error" 
message: "The server encountered an unexpected condition which prevented it from fulfilling the request" 

If you are attempting to log into the OpenAM console, you will see the following message after the Internal Server Error has flashed up:

Unable to login to OpenAM

This issue can also be seen in the HTTP container logs. For example, an error similar to the following is shown in the catalina.out log if you are using Apache Tomcat™:

WARNING: Exception or error caught in server resource 
Internal Server Error (500) - The server encountered an unexpected condition which prevented it from fulfilling the request 
at org.restlet.resource.ServerResource.doHandle(ServerResource.java:517) 
at org.restlet.resource.ServerResource.post(ServerResource.java:1216) 
at org.restlet.resource.ServerResource.doHandle(ServerResource.java:592) 
at org.restlet.resource.ServerResource.doNegotiatedHandle(ServerResource.java:649) 
at org.restlet.resource.ServerResource.doConditionalHandle(ServerResource.java:348) 
at org.restlet.resource.ServerResource.handle(ServerResource.java:952) 
at org.restlet.resource.Finder.handle(Finder.java:246) 
at org.forgerock.openam.rest.service.VersionRouter.handle(VersionRouter.java:139) 
at org.forgerock.openam.rest.service.ServiceRouter$RestletWrapper.handle(ServiceRouter.java:162) 
...
Caused by: java.lang.NullPointerException
	at org.forgerock.openam.forgerockrest.authn.AuthIdHelper.generateAuthId(AuthIdHelper.java:174)
	at org.forgerock.openam.forgerockrest.authn.AuthIdHelper.createAuthId(AuthIdHelper.java:103)
	at org.forgerock.openam.forgerockrest.authn.RestAuthenticationHandler.createJsonCallbackResponse(RestAuthenticationHandler.java:320)
	at org.forgerock.openam.forgerockrest.authn.RestAuthenticationHandler.processAuthentication(RestAuthenticationHandler.java:246)
	at org.forgerock.openam.forgerockrest.authn.RestAuthenticationHandler.authenticate(RestAuthenticationHandler.java:160)
	at org.forgerock.openam.forgerockrest.authn.RestAuthenticationHandler.initiateAuthentication(RestAuthenticationHandler.java:93)
	at org.forgerock.openam.forgerockrest.authn.restlet.AuthenticationServiceV1.authenticate(AuthenticationServiceV1.java:133)
	at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
	at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
	at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)
	at java.lang.reflect.Method.invoke(Method.java:597)
	at org.restlet.resource.ServerResource.doHandle(ServerResource.java:503)
	... 70 more

If you are attempting to access the REST API, you will also see the following error in the restAuthenticationFilter log file:

restAuthenticationFilter:09/10/2015 04:27:19:029 PM CEST: Thread[http-bio-8080-exec-30,5,main] 
Access Denied 
org.forgerock.jaspi.exceptions.JaspiAuthException: Access Denied 
at org.forgerock.jaspi.runtime.context.ContextHandler.handleCompletion(ContextHandler.java:131) 
at org.forgerock.jaspi.runtime.context.JaspiServerAuthContext.validateRequest(JaspiServerAuthContext.java:244) 
at org.forgerock.jaspi.runtime.JaspiRuntime.processMessage(JaspiRuntime.java:160) 
at org.forgerock.jaspi.JaspiRuntimeFilter.doFilter(JaspiRuntimeFilter.java:131) 
at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:243)
at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:210) 
at org.forgerock.openam.validation.ResponseValidationFilter.doFilter(ResponseValidationFilter.java:44) 
...
Caused by: org.forgerock.json.resource.PermanentException: Access Denied
        at org.forgerock.json.resource.ResourceException.getException(ResourceException.java:251)
        at org.forgerock.json.resource.ResourceException.getException(ResourceException.java:181)
        at org.forgerock.jaspi.runtime.context.ContextHandler.handleCompletion(ContextHandler.java:129)
        ... 25 more

Recent Changes

Imported a new signing key into the keystore and changed the certificate alias for SAML2 or OAuth.

Causes

The default 'test' certificate alias used for SAML2 and OAuth signing keys is also used by the XUI and for REST authentication as of OpenAM 12.x. 

The procedure in the OpenAM 12 Admin Guide: To Change the Signing Key for Federation describes creating a new keystore.jks and replacing the default keystore.jks with the newly created one. This process removes the default 'test' alias and replaces it with a newly created alias. If you follow this procedure but do not change the certificate alias used for authentication, you will not be able to log into the OpenAM console with XUI enabled or make REST calls.

Solution

This issue can be resolved by updating the certificate alias to match the alias of the new signing key using either the OpenAM console or ssoadm. You can either do this globally or per realm:

Globally:

  • OpenAM 13.5 console: navigate to: Configure > Authentication > Core Attributes > Security > Persistent Cookie Encryption Certificate Alias and enter the alias of the new signing key.
  • OpenAM 13 console: navigate to: Configuration > Authentication > Core > Security > Persistent Cookie Encryption Certificate Alias and enter the alias of the new signing key.
  • Pre-OpenAM 13 console: navigate to: Configuration > Authentication > Core > Security > Organization Authentication Certificate Alias and enter the alias of the new signing key.
  • ssoadm: enter the following command:
    $ ./ssoadm set-attr-defs -s iPlanetAMAuthService -t organization -u [adminID] -f [passwordfile] -a iplanet-am-auth-key-alias=[signingkeyalias]
    replacing [adminID], [passwordfile] and [signingkeyalias] with appropriate values.

Realm:  

  • OpenAM 13 and later console: navigate to: Realms > [Realm Name] > Authentication > Settings > Security > Persistent Cookie Encryption Certificate Alias and enter the alias of the new signing key.
  • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Authentication > All Core Settings > Security > Organization Authentication Certificate Alias and enter the alias of the new signing key.
  • ssoadm: enter the following command:
    $ ./ssoadm set-realm-svc-attrs -s iPlanetAMAuthService -e [realmname] -u [adminID] -f [passwordfile] -a iplanet-am-auth-key-alias=[signingkeyalias]
    replacing [realmname], [adminID], [passwordfile] and [signingkeyalias] with appropriate values.
Note

You must restart the web application container in which OpenAM runs to apply these configuration changes.

See Also

How do I change the Signing Key for Federation in OpenAM 12.x and 13.x?

Login to AM/OpenAM console (All versions) fails for amadmin user

FAQ: SAML certificate management in AM/OpenAM

Related Training

N/A

Related Issue Tracker IDs

OPENAM-6003 (value for 'iplanet-am-auth-key-alias' should be checked when saving)

OPENAM-6824 (Procedure To Change the Signing Key for Federation results in being locked out of XUI)


SP initiated logout fails in AM/OpenAM (All versions) with Identity Provider ID is null error

The purpose of this article is to provide assistance if a SP initiated logout fails in AM/OpenAM with an "Identity Provider ID is null" error. For example, your logout URL is similar to: http://sp.example.com:8080/openam/saml2/jsp/spSingleLogoutInit.jsp?binding=urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect

Symptoms

An error similar to the following is shown when the logout URL is called:

HTTP 400 
type Status report 
message Identity Provider ID is null. 
description The request sent by the client was syntactically incorrect (Identity Provider ID is null.).

Recent Changes

Configured SAML 2.0 Federation to initiate SLO from the service provider side.

Causes

The identity provider cannot be identified due to incorrect or missing idpEntityID.

Solution

This issue can be resolved by including idpEntityID in the logout URL (which is a required parameter for Fedlets). This parameter identifies the remote identity provider and is the value you specified when you registered the remote identity provider, which is typically the FQDN. This value should be URL encoded.

An example URL for a SP initiated logout using HTTP-Redirect binding is: 

http://sp.example.com:8080/openam/saml2/jsp/spSingleLogoutInit.jsp?metaAlias=/sp&idpEntityID=http%3A%2F%2Fidp.acme.com%3A8080%2Fopenam&binding=urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect
Note

The spSingleLogoutInit.jsp element of the URL is case sensitive and the URL will fail if this is in the wrong case. For example, including spsinglelogoutinit.jsp in the URL will not work.

See Also

How do I configure IdP or SP initiated Single Logout in AM/OpenAM (All versions)?

FAQ: SAML federation in AM/OpenAM

SAML Federation in AM/OpenAM

SAML v2.0 Guide › Implementing SAML v2.0 Using the AM Console › Implementing SAML v2.0 Single Sign-On and Single Logout

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs

OPENAM-3806 (SP initiated logout should not fail if SLO binding is not supported locally)


SP initiated login fails in AM/OpenAM (All versions) with Service Provider ID is null error

The purpose of this article is to provide assistance if a SP initiated login fails in AM/OpenAM with an error, "Service Provider ID is null". The request sent by the client was syntactically incorrect. For example, your login URL is similar to: http://sp.example.com:8080/openam/saml2/jsp/spSSOInit.jsp

Symptoms

An error similar to the following is shown in the browser when the login URL is called:

HTTP Status 400 - Service Provider ID is null. 
type Status report 
message Service Provider ID is null. 
description The request sent by the client was syntactically incorrect.

Recent Changes

Configured SAML 2.0 Federation to initiate SSO from the service provider side.

Causes

The identity provider cannot be identified due to incorrect or missing metaAlias.

Solution

This issue can be resolved by including metaAlias in the login URL (which is a required parameter). This parameter specifies the local alias for the service provider.

An example URL for a SP initiated login is: 

http://sp.example.com:8080/openam/saml2/jsp/spSSOInit.jsp?metaAlias=/sp&idpEntityID=http%3A%2F%2Fidp.acme.com%3A8080%2Fopenam
Note

The spSSOInit.jsp element of the URL is case sensitive and the URL will fail if this is in the wrong case. For example, including spssoinit.jsp in the URL will not work.

See Also

How do I configure IdP or SP initiated Single Sign On in AM/OpenAM (All versions)?

How do I redirect to a specific page after a successful IdP or SP initiated login in AM/OpenAM (All versions)?

FAQ: SAML federation in AM/OpenAM

SAML Federation in AM/OpenAM

SAML v2.0 Guide › Implementing SAML v2.0 Using the AM Console › Implementing SAML v2.0 Single Sign-On and Single Logout

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs

N/A


Copyright and TrademarksCopyright © 2018 ForgeRock, all rights reserved.

This content has been optimized for printing.

Loading...