How do I automate the creation of a SAML2 entity provider in AM/OpenAM (All versions)?

How To

Last updated Feb 26, 2019

The purpose of this article is to provide information on creating an IdP or SP (hosted or remote) using either the REST API in AM/OpenAM or Amster in AM.

Overview

When creating SAML2 entity providers using either the REST API or Amster, you should be aware of the following key points:

The entity ID must not contain slashes else creation will fail with a 400 response as detailed in 400 response when adding or updating resources via REST or Amster when the resource name contains forward slashes in AM/OpenAM (All versions).
You must pass the metadata and extended metadata XML documents in the body/payload of the request.
Characters in the XML documents must be escaped correctly. In particular, you must escape double quotes (") as follows:
- REST - escaped with a single backslash, for example \"
- Amster - escaped with a double backslash, for example \\"

Hosted and remote entity providers are identified in the entityConfig field of the body/payload by the value of the hosted element (true or false), for example:

REST:

Hosted identity providers:

"entityConfig": "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?><EntityConfig entityID=\"hostedEntityProviderID\" hosted=\"true\" ...

Remote entity providers:

"entityConfig": "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?><EntityConfig entityID=\"remoteEntityProviderID\" hosted=\"false\" ...

Amster:

Hosted identity providers:

"entityConfig": "<?xml version=\\"1.0\\" encoding=\\"UTF-8\\" standalone=\\"yes\\"?><EntityConfig entityID=\\"hostedEntityProviderID\\" hosted=\\"true\\" ...

Remote entity providers:

"entityConfig": "<?xml version=\\"1.0\\" encoding=\\"UTF-8\\" standalone=\\"yes\\"?><EntityConfig entityID=\\"remoteEntityProviderID\\" hosted=\\"false\\" ...

This article details the automation options available for creating entity providers:

REST API
Amster (AM 5 and later)
ssoadm (deprecated as of AM 5) - see the following articles for further information:
- 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?

Creating an entity provider using the REST API

Note

Please observe the following when constructing REST calls:

Make the REST call to the actual AM/OpenAM server URL (not lb).
Change the name of the iPlanetDirectoryPro header to the name of your actual session cookie.
Set this session cookie header to the token returned when you authenticated.
Ensure the Accept-API-Version header contains valid resource versions (AM 5 and later).

See How do I avoid common issues with REST calls in AM/OpenAM (All versions)? for further information.

You can create an entity provider using the REST API as follows:

Ensure you have the metadata and extended metadata XML documents; either generated yourself if you are the hosted entity provider or received from the remote entity provider.
Ensure any characters in the XML documents are escaped correctly, for example, escaping " with a single backslash (\").

Authenticate as an admin user. For example:

$ curl -X POST -H "X-OpenAM-Username: amadmin" -H "X-OpenAM-Password: cangetinam" -H "Content-Type: application/json" -H "Accept-API-Version: resource=2.1" http://host1.example.com:8080/openam/json/realms/root/authenticate

Example response:

{ "tokenId": "AQIC5wM2LY4SfcxsuvGEjcsppDSFR8H8DYBSouTtz3m64PI.*AAJTSQACMDIAAlNLABQtNTQwMTU3NzgxODI0NzE3OTIwNAEwNDU2NjE0*", "successUrl": "/openam/console", "realm": "/" }

Create the SAML2 entity provider using the following curl command, where entityID in the URL is replaced with the name of your entity provider:

$ curl -X PUT -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" -H "Content-Type: application/json" -H "Accept-API-Version: resource=1.0" -H "If-None-Match: *" -d '{"metadata": "<?xml version=\"1.0\" encoding=\"UTF-8\" ... ","entityConfig": "<?xml version=\"1.0\" encoding=\"UTF-8\" ... "}' 
'http://host1.example.com:8080/openam/json/realms/root/realm-config/federation/entityproviders/saml2/entityID'

Example response (this has been abbreviated due to the size of response):

{
  "_id": "entityID",
  "_rev": "1045663808",
  "metadata": "<?xml version=\"1.0\" encoding=\"UTF-8\" ... ",
  "entityConfig": "<?xml version=\"1.0\" encoding=\"UTF-8\" ... ",
  "_type": {
    "_id": "saml2",
    "name": "Entity Descriptor ",
    "collection": true
  }
}

Note

You can put the data payload in a file and then pass the file instead of the raw data using the following format:

-d "@/path/to/filename"

See curl -d, --data <data> for further information.

Creating an entity provider using Amster

You can create an entity provider using Amster as follows:

Ensure you have the metadata and extended metadata XML documents; either generated yourself if you are the hosted entity provider or received from the remote entity provider.
Ensure any characters in the XML documents are escaped correctly, for example, escaping " with a double backslash (\\").

Create the SAML2 entity provider:

$ create Saml2Entity --realm / --id entityProviderID --body '{"metadata": "<?xml version=\\"1.0\\" encoding=\\"UTF-8\\" ... ","entityConfig": "<?xml version=\\"1.0\\" encoding=\\"UTF-8\\" ... "}'

Example response (this has been abbreviated due to the size of response):

===> {
    "metadata": "<?xml version=\"1.0\" encoding=\"UTF-8\" ... ",
    "entityConfig": "<?xml version=\"1.0\" encoding=\"UTF-8\" ... ",
    "_rev": "772106341",
    "_type": {
        "_id": "saml2",
        "name": "Entity Descriptor ",
        "collection": true
    },
    "_id": "entityProviderID"
}

Related Training

N/A

Related Issue Tracker IDs

OPENAM-12334 (Unable to create Saml2Entity using Amster)