# OpenAM Administration Guide
Chapter 12. Managing SAML 2.0 Federation

Sidebar | Prev | Up | Next

## 12.2. Setting Up SAML 2.0 SSO

Before you set up SAML 2.0 SSO in OpenAM, you must:

- Know which providers participate in the circle of trust.

- Know how OpenAM installations act as identity providers, or service providers.

- Agree with other providers on a synchronized time service.

- For identity information exchanged with other participants in a circle of trust, define how to map shared user attributes. Local user profile attribute names should map to user profile attribute names at other providers.

  For example, if you exchange user identifiers with your partners, and you call it `uid` whereas another partner calls it `userid`, then you map your `uid` to your partner's `userid`.

- Import the keys used to sign assertions into the JKS key store in your OpenAM configuration directory. You can use the Java keytool command.

  The OpenAM configuration key store is located at the top level of the configuration directory, such as `$HOME/openam/keystore.jks`. The password, stored in `$HOME/openam/.keypass`, is `changeit` by default. Also by default the only key available is for a self-signed certificate (alias: test) installed with OpenAM.

During set up, you must share metadata for providers that you host with other providers in the circle of trust. You must also configure remote providers, connecting to other providers by importing their metadata.

In OpenAM terms, a hosted provider is one served by the current OpenAM server, whereas a remote provider is one hosted elsewhere.

This section covers the following topics.

- Procedure 12.1, “To Create a Hosted Identity Provider”

- Procedure 12.2, “To Create a Hosted Service Provider”

- Procedure 12.3, “To Create a Remote Identity Provider”

- Procedure 12.4, “To Create a Remote Service Provider”

- Procedure 12.5, “To Create a Fedlet for Service Providers”

- Section 12.2.1, “Deploying the Identity Provider Discovery Service”

Procedure 12.1. To Create a Hosted Identity Provider

1. On the OpenAM console Common Tasks page, click Create Hosted Identity Provider.

2. Unless you already have metadata for the provider, accept the Name for this identity provider in the field provided, or provide your own unique identifier.

   The default name is the URL to the current server which hosts the identity provider.

3. Select the Signing Key you imported into the OpenAM key store.

4. Either add the provider to the circle of trust you already created, or select Add to new and provide a New Circle of Trust name.

5. For the attributes you share, map service provider attribute names (Name in Assertion), to user profile names from your identity repository (Local Attribute Name).

   The default IDP mapping implementation allows you to add static values in addition to values taken from the user profile. You add a static value by enclosing the profile attribute name in double quotes (`"`), as in the following examples.

   To add a static SAML attribute called `partnerID` with a value of `staticPartnerIDValue`, add `partnerID` as the Name in Assertion with `"staticPartnerIDValue"` as the Local Attribute Name.

6. Click Configure to save your configuration.

7. Export the XML-based metadata from your provider to share with other providers in your circle of trust.

       $ curl -o metadata.xml
        http://www.idp.example:8080/openam/saml2/jsp/exportmetadata.jsp?entityid=
        http://www.idp.example:8080/openam&realm=/realm-name

   When you have configured only the top-level realm, `/`, you can omit the query string.

   Alternatively, provide the URL, to other providers so they can load the metadata.

Procedure 12.2. To Create a Hosted Service Provider

1. On the OpenAM console Common Tasks page, click Create Hosted Service Provider.

2. Unless you already have metadata for the provider, accept the Name for this service provider in the field provided, or provide your own unique identifier.

   The default name is the URL to the current server which hosts the service provider.

3. Either add the provider to the circle of trust you already created, or select Add to new and provide a New Circle of Trust name.

4. If the identity provider has not already mapped the attributes you share, map identity provider attribute names (Name in Assertion), to user profile names from your identity repository (Local Attribute Name).

5. Click Configure to save your configuration.

6. Export the XML-based metadata from your provider to share with other providers in your circle of trust.

       $ curl -o metadata.xml
        http://www.sp.example:8080/openam/saml2/jsp/exportmetadata.jsp?entityid=
        http://www.sp.example:8080/openam&realm=/realm-name

   When you have configured only the top-level realm, `/`, you can omit the query string.

   Alternatively, provide the URL, to other providers so they can load the metadata.

Procedure 12.3. To Create a Remote Identity Provider

1. Obtain the identity provider metadata, or the URL where you can obtain it.

2. On the OpenAM console Common Tasks page, click Register Remote Identity Provider.

3. Provide the identity provider metadata or link to obtain metadata.

4. Either add the provider to the circle of trust you already created, or select Add to new and provide a New Circle of Trust name.

5. Click Configure to save your configuration.

Procedure 12.4. To Create a Remote Service Provider

1. Obtain the service provider metadata, or the URL where you can obtain it.

2. On the OpenAM console Common Tasks page, click Register Remote Service Provider.

3. Provide the identity provider metadata or link to obtain metadata.

4. If the identity provider has not already mapped the attributes you share, map identity provider attribute names (Name in Assertion), to user profile names from your identity repository (Local Attribute Name).

5. Either add the provider to the circle of trust you already created, or select Add to new and provide a New Circle of Trust name.

6. Click Configure to save your configuration.

Procedure 12.5. To Create a Fedlet for Service Providers

When your organization acts as the identity provider, and you want quickly to enable service providers to federate their services with yours, you can provide them with a fedlet. A fedlet is a small Java or .NET web application that can act as a service provider for a specific identity provider without requiring that you install all of OpenAM.

Fedlets support the following SAML 2.0 features.

Table 12.1. Fedlet Support for SAML 2.0 Features

SAML 2.0 Feature | Java Fedlet | .NET Fedlet
--- | --- | ---
IDP & SP-initiated Single Sign-On (HTTP Artifact) | Supported | Supported
IDP & SP-initiated Single Sign-On (HTTP POST) | Supported | Supported
IDP & SP-initiated Single Logout (HTTP POST) | Supported | Supported
IDP & SP-initiated Single Logout (HTTP Redirect) | Supported | Supported
Sign Requests & Responses | Supported | Supported
Encrypt Assertion, Attribute, & NameID Elements | Supported | Supported
Export SP Metadata | Supported | Supported
Attribute Queries | Supported | Supported
XACML Requests | Supported | Not supported
Multiple IDPs | Supported | Supported
External IDP Discovery Service | Supported | Supported
Bundled IDP Reader Service for Discovery | Supported | Not supported

For more information on using fedlets, see Using Fedlets in Java Web Applications and Using Fedlets in .NET Applications in the Developer's Guide.

The following procedure describes how to create a Java Fedlet.

1. If you have not done so already, set up your identity provider.

2. Enter the URL where the service provider will deploy the fedlet you create, and name the fedlet. If you create multiple fedlets, use the URL as a unique name that shows who has deployed the fedlet.

3. For the attributes you share, map service provider attribute names (Name in Assertion), to user profile names from your identity repository (Local Attribute Name).

4. Click Create to generate the `Fedlet.zip` file under the OpenAM configuration directory, such as `$HOME/openam/myfedlets/httpwwwexamplecom80myapp/Fedlet.zip`.

5. Give the `Fedlet.zip` file to the service provider for deployment.