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 (AM 5 and later)
- ssoadm (deprecated as of AM 5) - 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 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 (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" http://host1.example.com:8080/openam/json/realms/root/authenticate?authIndexType=service&authIndexValue=adminconsoleserviceExample response: { "tokenId": "AQIC5wM2LY4SfcxsuvGEjcsppDSFR8H8DYBSouTtz3m64PI.*AAJTSQACMDIAAlNLABQtNTQwMTU3NzgxODI0NzE3OTIwNAEwNDU2NjE0*", "successUrl": "/openam/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 "http://host1.example.com:8080/openam/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 "http://host1.example.com:8080/openam/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 (pre-AM 7)
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.
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" http://host1.example.com:8080/openam/json/realms/root/authenticate?authIndexType=service&authIndexValue=adminconsoleserviceExample 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 } }
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