The Identity Federation Wiring REST API is designed to support establishment and management of federation agreements. It facilitates SAML metadata exchange between the Identity Provider partner and a Service Provider partner and enables or disables federation SSO between those two partners. This chapter describes the Oracle Access Management Identity Federation API. This chapter includes the following topics:
This chapter uses cURL to demonstrate the REST calls that the identity federation client sends to the identity federation server. cURL is free software that you can download from the cURL website at http://curl.haxx.se/
Using cURL to send REST calls to the server can help you better understand how the client interacts with the server. It can also be a helpful troubleshooting tool. Consider the following when using this chapter.
cURL commands that contain single quotes ( '
) will fail on Windows. When possible, use double quotes ( "
) in place of single quotes.
If a command requires both single quotes and double quotes, escape the double quotes with a backslash (for example: \"
) and replace the single quotes with double quotes.
Note:
In this guide, line breaks in cURL commands and server responses are for display purposes only.In addition to this Oracle Fusion Middleware Developer's Guide for Oracle Access Management, the Oracle Fusion Middleware User Provisioning Plug-in Java API Reference for Oracle Access Management Identity Federation is available.
Resource URLs are structured to include the Access Manager product version, the component exposed by the REST service, and the resources being invoked. The basic structure of a resource URL is as follows:
http(s)://
host
:port
/oam/services/rest/
path
where:
host is the host where the OAM Admin Service is running.
port is the HTTP or HTTPS port.
path is the relative path that identifies a particular resource. path is constructed as /version/component/service/ where:
version - is the Access Manager product version, such as 11.1.2.0.0
component - is the component exposed by the RESTful service, such as ssa or fed
service - is the root resource for that given API, such as hostidentifier
An example of a path value is: /oam/services/rest/11.1.2.0.0/fed/admin/sso/hostidentifier/
host_identifier_name.
The Access Manager identity federation REST Web Application Description Language (WADL) file lists the supported policy resources and methods. The Policy Administration REST WADL document is available at http://
host:port
/oam/services/rest/11.1.2.0.0/fed/admin/application.wadl
.
Access Manager identity federation services are mapped to URL resources. Each resource is referenced by a global identifier (URI).
Access to URL resources is based on user role. The RESTful service expects user credentials to be present in the Authentication header of the HTTP request in BASIC mode. If the authenticated user has the policy administration role, the requested policy administration action is performed.
Table 18-1 provides detail about each identity federation resource, the supported HTTP methods, and the results of each action.
Table 18-1 Access Manager Identity Federation Resources Summary
Resource | Method | Description |
---|---|---|
|
POST |
Enable Federation SSO service on the server and configure the logout done URL. |
PUT |
Same as POST operation. |
|
GET |
Get the enable status of the Federation SSO service and the logout done URL |
|
|
POST |
A service provider (SP) or identity provider (IdP) partner resource is created. The request is performed on the resource that is the parent of the object. A partner resource matching the request is created. |
|
GET |
A list of IdP partners is retrieved by this method. |
|
GET |
A list of SP partners is retrieved by this method. The resource that represents the Resource Types object is returned. This representation contains the matching Resource Type resource attributes and their values. |
|
POST |
A specific IdP partner resource is created by this method, where partnerName is the name of the partner to be created. |
PUT |
Same as POST operation. |
|
GET |
A specified IdP partner resource is retrieved by this method, where partnerName is the name of the IDP partner requested. |
|
DELETE |
A specified IdP partner resource is deleted by this method. |
|
|
POST |
A specific SP partner resource is created by this method, where partnerName is the name of the partner to be created. |
PUT |
Same as POST operation. |
|
GET |
A specified SP partner resource is retrieved by this method, where partnerName is the name of the SP partner requested. |
|
DELETE |
A specified SP partner resource is deleted by this method. The SP partner resource matching the ID or NAME query parameters is deleted. |
|
|
POST |
A client uses this service to connect two federation servers to remote REST services by this method. In this case both the federation servers are OAM installations |
|
POST |
A test SP resource is enabled or disabled by this method. |
PUT |
Same as POST operation. |
|
GET |
A test SP resource is retrieved by this method. |
|
|
POST |
A local server for local authentication or federation SSO is created using this method. This REST service is published on the Access Management Admin Server for backward compatibility where the OIF 11gR1 server or existing OIF REST clients will connect to those services. The input data type is FORM POST data. |
|
POST |
A specific SP partner resource is created using this method. This REST service is published on the Access Management Admin Server for backward compatibility where the OIF 11gR1 server or existing OIF REST clients will connect to those services. The input data type is FORM POST data. |
|
POST |
A specific IdP partner resource is created by this method. This REST service is published on the Access Management Admin Server for backward compatibility where the OIF 11gR1 server or existing OIF REST clients will connect to those services. The input data type is FORM POST data. |
|
POST |
A client uses this service to connect two federation servers to remote REST services. This REST service is published on the Access Management Admin Server for backward compatibility where the OIF 11gR1 server or existing OIF REST clients will connect to those services. The input data type is FORM POST data. |
|
POST |
A test SP resource is enabled or disabled by this method. This REST service is published on the Access Management Admin Server for backward compatibility where the OIF 11gR1 server or existing OIF REST clients will connect to those services. The input data type is FORM POST data. |
|
POST |
Re-directs the respective fedrest url to /oam/services/rest/11.1.2.0.0/fed/admin/ssoservice. This is used to create a local server for local authentication or federation SSO. This REST service is published on the Access Management Admin Server for backward compatibility where the OIF 11gR1 server or existing OIF REST clients will connect to those services.The input data type is FORM POST data. |
|
POST |
Re-directs the respective fedrest url to /oam/services/rest/11.1.2.0.0/fed/admin/trustedsppartners. This is used to create a specific SP partner resource. This REST service is published on the Access Management Admin Server for backward compatibility where the OIF 11gR1 server or existing OIF REST clients will connect to those services. The input data type is FORM POST data. |
|
POST |
Re-directs the respective fedrest url to /oam/services/rest/11.1.2.0.0/fed/admin/trustedidppartners. This is used to create a specific IdP partner resource. This REST service is published on the Access Management Admin Server for backward compatibility where the OIF 11gR1 server or existing OIF REST clients will connect to those services. The input data type is FORM POST data. |
|
POST |
Re-directs the respective fedrest url to /oam/services/rest/11.1.2.0.0/fed/admin/orchestratorservice. This service is used by a client to connect two federation servers to remote REST services. This REST service is published on the Access Management Admin Server for backward compatibility where the OIF 11gR1 server or existing OIF REST clients will connect to those services. The input data type is FORM POST data. |
The following examples are provided as reference.
The REST endpoint/oam/services/rest/11.1.2.0.0/fed/admin/sso
request is used to configure the SSO service when the customer is the identity provider using the POST method.
This API is used for wiring with Fusion Applications and it configures the FAAuthScheme.
For Fusion Applications, IdP is configured at global level to:
Enable SAML 2.0 only.
Enable SSO POST, SSO Artifact, SLO Redirect profiles only.
NameID
Email Address with mail as the attribute of the user.
Unspecified with uid as the attribute of the user (default).
One set of keys/certificates for SAML operations.
OAM/Fed will be able to have specific SP Partner configuration:
SSO binding to be used.
NameID format and value to be used.
NameID format and value to be used.
Extra attributes to be sent
NameID value sent as an attribute: SP Partner will indicate the SAML Attribute name, and whether to send user's ID or email address.
Static attribute value used by the SP during Assertion mapping operations: SP Partner will indicate the SAML Attribute name and its value.
When IdP needs to authenticate the user, it will redirect the user to an URL protected by WebGate OAM with the FAAuthScheme:
If OAM is configured for local authentication, FAAuthScheme will instruct OAM to display a login page for the user to enter its credentials.
If OAM is configured for Federation SSO, FAAuthScheme will instruct OAM to start a Federation SSO flow by redirecting the user to SaaS OIF/SP.
If OAM is configured to let the user decide how to authenticate, FAAuthScheme will instruct OAM to display a chooser page and to then perform a local authentication or Federation SSO operation, depending on the user's choice.
The following is a sample file for this cURL command
Where
ssoFederation
is the setting in FAAuthScheme that enables federated SSO for the protected resource.
ssoFederation = ,
= ,
=
ssoChooser
is the setting that enables the login page to show both federated SSO link and local login with username and password.
oamLogoutDoneURL
is the URL to redirect after user has been logged out through single logout.
curl -X POST -H "Content-Type: application/json" -d '{"ssoFederation": "true", "ssoChooser": "false", "oamLogoutDoneURL": "http://test.com/customLogout"}' http://hostname:7001/oam/services/rest/11.1.2.0.0/fed/admin/sso --user USER:PASSWORD
Return result:
{"status":"1","statusMessage":""}
The REST endpoint/oam/services/rest/11.1.2.0.0/fed/admin/sso
request is used to retrieve the SSO service information when the customer is the identity provider using the GET method. The following is a sample file for this cURL command
curl -u USER:PASSWORD --request GET 'http://hostname:7001/oam/services/rest/11.1.2.0.0/fed/admin/sso'
Return result:
{"ssoFederation":"true","ssoChooser":"false","oamLogoutDoneURL":"http://test.com/customLogout"}
The REST endpoint/oam/services/rest/11.1.2.0.0/fed/admin/sso
request is used to configure the SSO service when the customer is the identity provider using the PUT method. The following is a sample file for this cURL command
curl -X PUT -H "Content-Type: application/json" -d '{"ssoFederation": "false", "ssoChooser": "false", "oamLogoutDoneURL": ""}' http://hostname:7001/oam/services/rest/11.1.2.0.0/fed/admin/sso --user USER:PASSWORD
Return result:
{"status":"1","statusMessage":""}
The REST endpoint /oam/services/rest/11.1.2.0.0/fed/admin/trustedpartners/ sp/partnerName
request creates a Trusted Partners Service. The service used is the /trustedpartners/sp/acmeSP service, containing the name of the SP Partner.
The following is a sample file for this cURL command.
Where
metadataB64
is the hexadecimal string corresponding to base 64 encoding of the peer partner's metadata XML. When using curl, you will have to escape the + signs in the base 64 encoded metadata string.
ssoProfile
the SAML 2.0 SSO profile to use (artifact or httppost).
nameIDFormat
the NameID format used during Federation SSO. Possible values are emailaddress or unspecified. If emailaddress, then the NameID value of an Assertion created by the IdP will contain the user's email address; if unspecified, then the NameID value of an Assertion created by the IdP will contain the user's ID.
curl -X POST -H "Content-Type: application/json" -d '{ "metadataB64": "...", "partnerType": "sp", "partnerName": "acmeSP", "nameIDFormat": "unspecified", "ssoProfile": "httppost" }' http://<SERVER>:<PORT>/oam/services/rest/11.1.2.0.0/fed/admin/trustedpartners/sp/acmeSP --user <USER>:<PASSWORD>
Return result:
{ "status":"1", "statusMessage":"" }
The REST endpoint/oam/services/rest/11.1.2.0.0/fed/admin/trustedpartners/ sp
request retrieves a list of Trusted Partners Services. The following is a sample file for this cURL command.
curl -u USER:PASSWORD --request GET 'http://hostname:7001/oam/services/rest/11.1.2.0.0/fed/admin/trustedpartners/sp'
Return result:
{ "partnerInfoList": [ { "metadataB64":"...", "partnerName":"acmeSP", "nameIDFormat":"unspecified", "ssoProfile":"httppost", "providerID":"http://acme:7499/fed/sp", "assertionConsumerURL":"http://acme:7777/fed/sp/sso", "logoutRequestURL":"http://acme:7777/fed/idp/samlv20", "logoutResponseURL":"http://acme:7777/fed/idp/samlv20", "adminManualCreation":"false", "displaySigningCertDN":"CN=acme OIF Signing Certificate", "displaySigningCertIssuerDN":"CN=OIFCert", "displaySigningCertStart":"2014-10-07T06:32:16-07:00", "displaySigningCertExpiration":"2024-10-11T06:32:17-07:00", "displayEncryptionCertDN":" CN=acme OIF Enc Certificate", "displayEncryptionCertIssuerDN":"CN=OIFCert", "displayEncryptionCertStart":"2014-10-07T06:32:16-07:00", "displayEncryptionCertExpiration":"2024-10-11T06:32:17-07:00" }, { "metadataB64":"...", "partnerName":"ciscoSP", "nameIDFormat":"emailaddress", "ssoProfile":"httppost", "providerID":"http://cisco:7499/fed/sp", "assertionConsumerURL":"http://cisco:7777/fed/sp/sso", "logoutRequestURL":"http://cisco:7777/fed/idp/samlv20", "logoutResponseURL":"http://cisco:7777/fed/idp/samlv20", "lastNameAttrName":"lastname", "firstNameAttrName":"firstname", "userNameAttrName":"username", "emailAttrName":"email" "adminManualCreation":"false", "displaySigningCertDN":"CN=cisco OIF Signing Certificate", "displaySigningCertIssuerDN":"CN=OIFCert", "displaySigningCertStart":"2014-10-07T06:32:16-07:00", "displaySigningCertExpiration":"2024-10-11T06:32:17-07:00", "displayEncryptionCertDN":" CN=cisco OIF Enc Certificate", "displayEncryptionCertIssuerDN":"CN=OIFCert", "displayEncryptionCertStart":"2014-10-07T06:32:16-07:00", "displayEncryptionCertExpiration":"2024-10-11T06:32:17-07:00" } ] }
The REST endpoint /oam/services/rest/11.1.2.0.0/fed/admin/trustedpartners/ sp/partnerName request retrieves information for a specific Trusted Partners Service. The following is a sample file for this cURL command.
curl -u USER:PASSWORD --request GET 'http://hostname:7001/oam/services/rest/11.1.2.0.0/fed/admin/trustedpartners/sp/acmeSP'
Return result:
{ "metadataB64":"...", "partnerName":"acmeSP", "nameIDFormat":"unspecified", "ssoProfile":"httppost", "providerID":"http://acme:7499/fed/sp", "assertionConsumerURL":"http://acme:7777/fed/sp/sso", "logoutRequestURL":"http://acme:7777/fed/idp/samlv20", "logoutResponseURL":"http://acme:7777/fed/idp/samlv20", "adminManualCreation":"false", "displaySigningCertDN":"CN=acme OIF Signing Certificate", "displaySigningCertIssuerDN":"CN=OIFCert", "displaySigningCertStart":"2014-10-07T06:32:16-07:00", "displaySigningCertExpiration":"2024-10-11T06:32:17-07:00", "displayEncryptionCertDN":" CN=acme OIF Enc Certificate", "displayEncryptionCertIssuerDN":"CN=OIFCert", "displayEncryptionCertStart":"2014-10-07T06:32:16-07:00", "displayEncryptionCertExpiration":"2024-10-11T06:32:17-07:00" }
The REST endpoint /oam/services/rest/11.1.2.0.0/fed/admin/trustedpartners/ sp/partnerName request is used to modify information for a specific Trusted Partners Service. The following is a sample file for this cURL command.
curl -X PUT -H "Content-Type: application/json" -d '{ "metadataB64": "..." }' http://hostname:7001/oam/services/rest/11.1.2.0.0/fed/admin/trustedpartners/sp/acmeSP --user USER:PASSWORD
Return result:
{"status":"1","statusMessage":""}
The REST endpoint /oam/services/rest/11.1.2.0.0/fed/admin/trustedpartners/ sp/partnerName request is used to delete information for a specific Trusted Partners Service. The following is a sample file for this cURL command.
curl -u USER:PASSWORD --request DELETE 'http://hostname:7001/oam/services/rest/11.1.2.0.0/fed/admin/trustedpartners/sp/acmeSP'
Return result:
{"status":"1","statusMessage":""}
The REST endpoint /oam/services/rest/11.1.2.0.0/fed/admin/testsp service request is used to enable a test SP using the POST method. The following is a sample file for this cURL command.
curl -X POST -H "Content-Type: application/json" -d '{"enabled": "true"}' http://hostname:7001/oam/services/rest/11.1.2.0.0/fed/admin/testsp --user USER:PASSWORD
Return result:
{"status":"1","statusMessage":""}
The REST endpoint /oam/services/rest/11.1.2.0.0/fed/admin/testsp service request is used to retrieve test SP enablement details using the GET method. The following is a sample file for this cURL command.
curl -u USER:PASSWORD --request GET 'http://hostname:7001/oam/services/rest/11.1.2.0.0/fed/admin/testsp'
Return result:
{ "enabled":"true" }
The REST endpoint /oam/services/rest/11.1.2.0.0/fed/admin/testsp service request is used to disable a test SP using the PUT method. The following is a sample file for this cURL command.
curl -X PUT -H "Content-Type: application/json" -d '{"enabled": "false"}' http://hostname:7001/oam/services/rest/11.1.2.0.0/fed/admin/testsp --user USER:PASSWORD
Return result:
{"status":"1","statusMessage":""}
The /fedrest/configuresso request redirects the request url to the actual required url /oam/services/rest/11.1.2.0.0/fed/admin/ssoservice, which is used to configure the SSO service when the customer is the identity provider using the POST method.
The following is a sample file for the cURL command
curl -v -i -u <USER>:<PASSWORD> -X POST -d @ssoConfigureData.in http://<SERVER>:<PORT>/fedrest/configuresso
File ssoConfigureData.in:
spTenantName=&idpProviderID=& preverify=false&ssoFederation=true& ssoChooser=true&oamadminuser=<USER>& oamadminpassword=<PASSWORD>& oamadminhost=<SERVER>& oamadminport=<PORT>
curl -u <USER>:<PASSWORD> --data "spTenantName=""&idpProviderID=""& preverify="false"&ssoFederation="true"&ssoChooser="true"& oamadminuser="<USER>"&oamadminpassword="<PASSWORD>"&oamadminhost="<SERVER>"& oamadminport="<PORT>"&oamLogoutDoneURL=""" --request POST 'http://<SERVER>:<PORT>/oam/services/rest/11.1.2.0.0/fed/admin/ssoservice'; -X POST -d @ssoConfigureData.in http://<SERVER>:<PORT>/fedrest/configuresso
The /fedrest/createsp request redirects the request url to the actual required url /oam/services/rest/11.1.2.0.0/fed/admin/trustedsppartners, which creates a Trusted Partners Service.
The following is a sample file for this cURL command.
Where
ssoProfile
the SAML 2.0 SSO profile to use (artifact or httppost).
nameIDFormat
the NameID format used during Federation SSO. Possible values are emailaddress or unspecified. If emailaddress, then the NameID value of an Assertion created by the IdP will contain the user's email address; if unspecified, then the NameID value of an Assertion created by the IdP will contain the user's ID.
curl -v -i -u <USER>:<PASSWORD> -X POST -d @spCurlData.in http://<HOST>:<PORT>/fedrest/createsp
File spCurlData.in:
idpTenantName=&idpTenantURL=& spPartnerName=spPartner-sample& spProviderID=&metadata=&metadataURL=& assertionConsumerURL=&logoutRequestURL=& logoutResponseURL=&signingCert=&encryptionCert=& nameIDFormat=unspecified&ssoProfile=artifact& generateNewKeys=&validityNewKeys=&preverify=false& lastNameAttrName=&firstNameAttrName=&userNameAttrName=& emailAttrName=&staticAttrName=&staticAttrValue=&customAttrs= ...
curl -v -i -u <USER>:<PASSWORD> -X POST -d @spCurlData.in https://<SERVER>:<PORT>/oam/services/rest/11.1.2.0.0/fed/admin/trustedsppartners
File spCurlData.in:
idpTenantName=&idpTenantURL=& spPartnerName=spPartner-sample& spProviderID=&metadata=&metadataURL=& assertionConsumerURL=&logoutRequestURL=& logoutResponseURL=&signingCert=&encryptionCert=& nameIDFormat=unspecified&ssoProfile=artifact& generateNewKeys=&validityNewKeys=&preverify=false& lastNameAttrName=&firstNameAttrName=&userNameAttrName=& emailAttrName=&staticAttrName=&staticAttrValue=&customAttrs=...
The /fedrest/createidp request redirects the request url to the actual required url /oam/services/rest/11.1.2.0.0/fed/admin/trustedidppartners, which creates a Trusted IdP Partner Service.
The following is a sample file for this cURL command.
Where
ssoProfile
the SAML 2.0 SSO profile to use (artifact or httppost).
nameIDFormat
the NameID format used during Federation SSO. Possible values are emailaddress or unspecified. If emailaddress, then the NameID value of an Assertion created by the IdP will contain the user's email address; if unspecified, then the NameID value of an Assertion created by the IdP will contain the user's ID.
curl -v -i -u <USER>:<PASSWORD> -X POST -d @idpCurlData.in http://<SERVER>:<PORT>/fedrest/createidp
File idpCurlData.in:
spTenantName=&spTenantURL=& idpPartnerName=idpPartner-sample& idpProviderID=&metadata=&metadataURL=& ssoURL=&ssoSOAPURL=&logoutRequestURL= &logoutResponseURL=&signingCert=& encryptionCert=&succinctID=& nameIDFormat=emailaddress&attributeLDAP=& attributeSAML=&ssoProfile=artifact&faWelcomePage= &tenantKeyName=&tenantKeyValue=&generateNewKeys=& validityNewKeys=&preverify=false
curl -v -i -u <USER>:<PASSWORD> -X POST -d @idpCurlData.in https://<SERVER>:<PORT>/oam/services/rest/11.1.2.0.0/fed/admin/trustedidppartners
File idpCurlData.in:
spTenantName=&spTenantURL=& idpPartnerName=idpPartner-sample& idpProviderID=&metadata=&metadataURL=& ssoURL=&ssoSOAPURL=&logoutRequestURL=& logoutResponseURL=&signingCert=& encryptionCert=&succinctID=& nameIDFormat=emailaddress&attributeLDAP=& attributeSAML=&ssoProfile=artifact&faWelcomePage=& tenantKeyName=&tenantKeyValue=&generateNewKeys=& validityNewKeys=&preverify=false
The /fedrest/orchestrator request redirects the request url to the actual required url /oam/services/rest/11.1.2.0.0/fed/admin/orchestrator, which connect two federation servers to remote REST services.
The following are sample files for the cURL commands.
Where
ssoProfile
the SAML 2.0 SSO profile to use (artifact or httppost).
nameIDFormat
the NameID format used during Federation SSO. Possible values are emailaddress or unspecified. If emailaddress, then the NameID value of an Assertion created by the IdP will contain the user's email address; if unspecified, then the NameID value of an Assertion created by the IdP will contain the user's ID.
curl -v -i -u <USER>:<PASSWORD> -X POST -d @orch.in http://<SERVER>:<PORT>/fedrest/orchestrator
File orch.in:
command=setupSPAndIdPTrust&spresturl=https://<SERVER>:<PORT>/fedrest/createidp&spadminuser=<USER>&spadminpassword=<PASSWORD>&spmetadataurl=&idpPartnerName=sample-idp&sptype=oif&idpresturl=http://<SERVER>:<PORT>/fedrest/createsp&idpadminuser=<USER>&idpadminpassword=<PASSWORD>&idpmetadataurl=&spPartnerName=sample-sp&idptype=oif&nameIDFormat=emailaddress&ssoProfile=httppost
Note:
idpmetadataurl and spmetadataurl should be url encoded.curl -v -i -u <USER>:<PASSWORD> -X POST -d @orch.in https://<SERVER>:<PORT>/oam/services/rest/11.1.2.0.0/fed/admin/orchestratorservice
File orch.in:
command=setupSPAndIdPTrust&spresturl=http://<SERVER>:<PORT>/oam/services/rest/11.1.2.0.0/fed/admin/trustedidppartners&spadminuser=<USER>&spadminpassword=<PASSWORD>&spmetadataurl=&idpPartnerName=sample-idp&sptype=oif&idpresturl=http://<SERVER>:<PORT>/oam/services/rest/11.1.2.0.0/fed/admin/trustedsppartners&idpadminuser=<USER>&idpadminpassword=<PASSWORD>&idpmetadataurl=&spPartnerName=sample-sp&idptype=oif&nameIDFormat=emailaddress&ssoProfile=httppost