How do I create a SAML2 IdP or SP entity provider in AM/OpenAM (All versions) using REST or Amster?

Overview

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

• REST API:
  • AM 7 and later
  • Pre-AM 7
• 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?

REST API (AM 7 and later)

New /saml2 REST endpoints have been added in AM 7, which allow you to pass JSON in the body/payload of the request. You can still use the federation/entityproviders/saml2 endpoints detailed under pre-AM 7 if you want to pass the XML documents, but you will need to make the changes detailed below.

Amster (All versions) and REST API (Pre-AM 7)

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\\" ...

-d "@/path/to/filename"

Creating an entity provider using the REST API (AM 7 and later)

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

1. 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?authIndexType=service&authIndexValue=adminconsoleservice
   

   Example response:

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

2. Create the SAML2 entity provider using one of the following curl commands, depending on whether you are creating a hosted or remote provider:
   • Hosted:

     $ curl -X POST "http://host1.example.com:8080/openam/json/realm-config/saml2/hosted#1.0_create_post" -H "accept: application/json" -H "Accept-API-Version: resource=1.0" -H "Content-Type: application/json" -d "{ [JSON payload] }"
     

   • Remote:

     $ curl -X POST "http://host1.example.com:8080/openam/json/realm-config/saml2/remote?_action=importEntity" -H "accept: application/json" -H "Accept-API-Version: resource=1.0" -H "Content-Type: application/json" -d "{ \"standardMetadata\": \"string\"}"
     

   You can try this out in the API Explorer.

Creating an entity provider using the REST API (pre-AM 7)

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

1. 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.
2. Ensure any characters in the XML documents are escaped correctly, for example, escaping " with a single backslash (\").
3. 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?authIndexType=service&authIndexValue=adminconsoleservice
   

   Example response:

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

4. 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
     }
   }

Creating an entity provider using Amster

You can create an entity provider using Amster as follows:

1. 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.
2. Ensure any characters in the XML documents are escaped correctly, for example, escaping " with a double backslash (\\").
3. 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"
   }

See Also

FAQ: SAML federation in AM/OpenAM

SAML Federation in AM/OpenAM

Using the REST API in AM/OpenAM

Using Amster in AM

Entity Reference › Saml2Entity

Related Training

N/A

Related Issue Tracker IDs

OPENAM-12334 (Unable to create Saml2Entity using Amster)