How do I create a SAML2 IdP or SP entity provider in AM (All versions) using REST or Amster?
The purpose of this article is to provide information on creating a SAML2 IdP or SP (hosted or remote) using either the REST API in AM or Amster in AM.
Overview
This article details the automation options available for creating entity providers:
- REST API:
- Amster
- ssoadm (deprecated) - see the following articles for further information:
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 as a base64 URL encoded string. You can still use the federation/entityproviders/saml2 endpoints detailed under AM 6.x if you want to pass the XML documents, but you will need to make the changes specified below.
Amster (All versions) and REST API (AM 6.x)
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 (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": "<EntityConfig entityID=\"hostedEntityProviderID\" hosted=\"true\" ...
- Remote entity providers: "entityConfig": "<EntityConfig entityID=\"remoteEntityProviderID\" hosted=\"false\" ...
- Amster:
- Hosted identity providers: "entityConfig": "<EntityConfig entityID=\\"hostedEntityProviderID\\" hosted=\\"true\\" ...
- Remote entity providers: "entityConfig": "<EntityConfig entityID=\\"remoteEntityProviderID\\" hosted=\\"false\\" ...
- REST:
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 the REST API (AM 7 and later)
Note
Please observe the following when constructing REST calls:
- Make the REST call to the actual AM 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.
See How do I avoid common issues with REST calls in AM (All versions)? for further information.
You can create an entity provider using the REST API as follows:
- 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" https://am.example.com:8443/am/json/realms/root/authenticate?authIndexType=service&authIndexValue=adminconsoleserviceExample response: { "tokenId": "AQIC5wM2LY4SfcxsuvGEjcsppDSFR8H8DYBSouTtz3m64PI.*AAJTSQACMDIAAlNLABQtNTQwMTU3NzgxODI0NzE3OTIwNAEwNDU2NjE0*", "successUrl": "/am/console", "realm": "/" }
-
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 "https://am.example.com:8443/am/json/realm-config/saml2/hosted#1.0_create_post" -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" -H "accept: application/json" -H "Accept-API-Version: resource=1.0" -H "Content-Type: application/json" -d '{ [JSON payload] }'
- Remote: $ curl -X POST "https://am.example.com:8443/am/json/realm-config/saml2/remote?_action=importEntity" -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" -H "accept: application/json" -H "Accept-API-Version: resource=1.0" -H "Content-Type: application/json" -d '{"standardMetadata":"base64urlencodedstring"}'
You can try this out in the API Explorer.
Creating an entity provider using the REST API (AM 6.x)
Note
Please observe the following when constructing REST calls:
- Make the REST call to the actual AM 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.
See How do I avoid common issues with REST calls in AM (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" https://am.example.com:8443/am/json/realms/root/authenticate?authIndexType=service&authIndexValue=adminconsoleserviceExample response: { "tokenId": "AQIC5wM2LY4SfcxsuvGEjcsppDSFR8H8DYBSouTtz3m64PI.*AAJTSQACMDIAAlNLABQtNTQwMTU3NzgxODI0NzE3OTIwNAEwNDU2NjE0*", "successUrl": "/am/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\" ... "}' 'https://am.example.com:8443/am/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:
- 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" }
See Also
Related Training
N/A
Related Issue Tracker IDs
N/A