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

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

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
   

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

-d "@/path/to/filename"

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)