REV 1.3
Table of Contents
Example Request #1 - Cirrus Bridge
Example Request #2 - Cirrus Proxy (SAMLV2 per IdP source)
Example Request #3 - Cirrus Proxy (SAMLV2 per SP target)
Example Request #4 - Cirrus Proxy (OIDC)
“attributeMode” Parameter Behavior
Example Response #1 - Basic response
Example Response #2 - Response with attributeMode set
Example Response #3 - Error message
Organizations frequently want to augment a SAML assertion, OIDC token or a CAS response with additional attributes. This article outlines the capabilities the API provided by the organization should have to enable integration with the Cirrus Bridge or Cirrus Authentication Proxy.
The APIs have the following constraints:
Cirrus will query a health check endpoint using the same credential used for the POST request. This endpoint is used to confirm connectivity and authorization to the API. Cirrus will perform a GET and the response should be 200 and the JSON:
{"status":"UP"}
Any other response or status code will be considered an error.
The Cirrus Authentication Proxy or Cirrus Bridge will HTTP-POST a JSON collection request to and expect a JSON collection response from a customer developed /attributes endpoint.
The general structure of the request consists of a series of context parameters and a block of “userAttributes”.
The context of the Attribute Authority backchannel call will be characterized by parameters included in the request. The following parameters may be present in the Request JSON collection depending on the deployment:
|
Context Parameter |
Definition |
Applicable Deployment Patterns |
|
"upstreamIdPEntityId" |
The upstream (source) SAML IdP entityId that was used to login. For example: “https://source.example.edu/idp” |
All deployments for Cirrus Proxy |
|
"downstreamSpEntityId" |
The downstream (target) SAML SP entityId that will receive the assertion. For example: “https://target.example.edu/sp” |
All SAMLV2 deployments when Cirrus Proxy or Bridge is configured to perform a separate Attribute Authority API call for each login request from a target service provider |
|
"cirrusIdPEntityId" |
The SAML entityId of the Cirrus Bridge or proxy that is being used by the downstream (target) service provider (SP). For example "https://tenant.proxy.cirrusidentity.com/idp" |
All SAMLV2 deployments for Cirrus Bridge or Proxy |
|
“downstreamRelyingParty” |
The downstream (target) OIDC RP that will receive the assertion. For example: _aaa111b22ccccc333d44f5aaa6666bb7777cc88dd9 |
All OIDC deployments when Cirrus Proxy configured to perform a separate Attribute Authority API call for each login request from a target RP |
|
“cirrusOIDCIssuer” |
The OIDC issuer string that is configured at the Cirrus Proxy. For example: https://example.proxy.cirrusidentity.com |
All OIDC deployments for Cirrus Proxy |
The userAttributes block of the request will contain a collection of the user attributes that were asserted by the upstream IdP. Each user attribute is reflected as:
The following is an example request with the following AA use case:
This use case will generate the following JSON request:
{
"upstreamIdPEntityId": "https://source.example.edu/idp",
"downstreamSpEntityId" : "https://target.example.edu/sp",
"cirrusIdPEntityId": "https://example.proxy.cirrusidentity.com/idp",
"userAttributes": {
"urn:oid:2.5.4.3": [
"firsty lasty"
],
"urn:oid:1.3.6.1.4.1.5923.1.1.1.6": [
"123456789@example.edu"
],
"urn:oid:1.3.6.1.4.1.5923.1.1.1.9": [
"member@example.edu"
],
"attributeWithoutOid": [
"value1",
"value2"
]
}
}
The following is an example request with context parameters for the following AA use case:
This use case will generate the following JSON request:
{
"upstreamIdPEntityId": "https://source.example.edu/idp",
"cirrusIdPEntityId": "https://example.proxy.cirrusidentity.com/idp",
"userAttributes": {
"urn:oid:2.5.4.3": [
"firsty lasty"
],
"urn:oid:1.3.6.1.4.1.5923.1.1.1.6": [
"123456789@example.edu"
],
"urn:oid:1.3.6.1.4.1.5923.1.1.1.9": [
"member@example.edu"
],
"attributeWithoutOid": [
"value1",
"value2"
]
}
}
The following is an example request with context parameters for the following AA use case:
This use case will generate the following JSON request:
{
"upstreamIdPEntityId": "https://source.example.edu/idp",
"downstreamSpEntityId" : "https://target.example.edu/sp",
"cirrusIdPEntityId": "https://example.proxy.cirrusidentity.com/idp",
"userAttributes": {
"urn:oid:2.5.4.3": [
"firsty lasty"
],
"urn:oid:1.3.6.1.4.1.5923.1.1.1.6": [
"123456789@example.edu"
],
"urn:oid:1.3.6.1.4.1.5923.1.1.1.9": [
"member@example.edu"
],
"attributeWithoutOid": [
"value1",
"value2"
]
}
}
The following is an example request with the following AA use case:
This use case will generate the following JSON request:
{
"upstreamIdPEntityId": "https://source.example.edu/idp",
"downstreamRelyingParty" : "_aaa111b22ccccc333d44f5aaa6666bb7777cc88dd9",
"cirrusOIDCIssuer": "https://example.proxy.cirrusidentity.com",
"userAttributes": {
"urn:oid:2.5.4.3": [
"firsty lasty"
],
"urn:oid:1.3.6.1.4.1.5923.1.1.1.6": [
"123456789@example.edu"
],
"urn:oid:1.3.6.1.4.1.5923.1.1.1.9": [
"member@example.edu"
],
"attributeWithoutOid": [
"value1",
"value2"
]
}
}
The customer developed API should respond with a JSON collection when receiving a HTTP POST request. The response should have the following possible keys:
NOTE - For Cirrus Bridges integrated with either Entra ID or Okta APIs, this attribute is ignored and has no effect. The combination behavior is controlled through the configured application in Entra ID or Okta.
The JSON key “attributeMode” is optional in the response collection when Attribute Authority is used with Cirrus Proxy and in cases where the Cirrus Bridge is deployed using an assertion for integration instead of APIs. Unless specified, attributeMode is “replace” by default. The behavior for the “attributeMode” is outlined in the table below:
|
attributeMode value |
Behavior |
|
replace (default if not set) |
All of the user’s existing attributes are removed and only attributes from the AA are used for the user. |
|
merge |
The user’s existing attributes are combined with those from the attribute authority. For example, if the user had the value “member” for eduPersonAffiliation attribute, and AA returns “staff” for eduPersonAffiliation, then assertion will be a multivalued attribute containing “member” and “staff” |
|
overwrite |
The attributes from the AA are added to the existing user attributes and any existing attribute with the same name as that from the AA is replaced. |
|
preserve |
Attributes added but any existing user attributes are preserved. e.g., if the attribute from the AA has the same name as a user’s existing attribute then it is not used. |
An example of a basic response that will “replace” the incoming assertion from the source IdP.
{
"status": "continue",
"userAttributes": {
"urn:oid:2.5.4.3": [
"Update Name"
],
"newAttribute": [
"abcd"
]
}
}
An example of using a “merge” attributeMode for the response to add the value of “staff@example.edu” to the eduPersonScopedAffiliation existing attribute:
{
"status": "continue",
"attributeMode": "merge",
"userAttributes": {
"urn:oid:1.3.6.1.4.1.5923.1.1.1.9": [
"staff@example.edu"
],
"newAttribute": [
"abcd"
]
}
}
An example of the attribute returning an error message that directs the end user to a URL for help.
{
"status": "error",
"message": "A user could not be found. You can **try again** or click [here](https://example.edu/help) for help."
}