REV 1.0 Table of Contents Overview
Attribute Authority and Flow Control API
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
Overview
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.
Basic Operation
The APIs have the following constraints:
- The Attribute Authority supports the HTTP Basic-Auth header. It does not currently support the HTTP X-Api-Key header. Contact Cirrus Identity Support (see https://www.cirrusidentity.com/resources/service-desk) for other supported authentication methods.
- All API calls originate from Cirrus Identity servers. The end user browser agent does not make any API calls.
Health Check Endpoint
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 “/attributes” endpoint
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.
/attributes Request
The general structure of the request consists of a series of context parameters and a block of “userAttributes”.
Context Parameters
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 |
User Attributes
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:
- A multi-valued array of string values
- Will have JSON keys that match either the OID or human readable name for the attribute based on what was asserted by the upstream IdP
Example Request #1 - Cirrus Bridge
The following is an example request with the following AA use case:
- A SAML V2 authentication transaction
- A Cirrus Bridge integration
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"
]
}
}
Example Request #2 - Cirrus Proxy (SAMLV2 per IdP source)
The following is an example request with context parameters for the following AA use case:
- A SAML V2 authentication transaction
- A Cirrus Authentication Proxy integration
- A Cirrus Authentication Proxy configured to perform a separate Attribute Authority API call for each login response from each source Identity Provider
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"
]
}
}
Example Request #3 - Cirrus Proxy (SAMLV2 per SP target)
The following is an example request with context parameters for the following AA use case:
- A SAML V2 authentication transaction
- A Cirrus Authentication Proxy integration
- A Cirrus Authentication Proxy configured to perform a separate Attribute Authority API call for each login request from a downstream service provider
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"
]
}
}
Example Request #4 - Cirrus Proxy (OIDC)
The following is an example request with the following AA use case:
- An OIDC authentication transaction
- A Cirrus Authentication Proxy integration
- A Cirrus Authentication Proxy configured to perform a separate Attribute Authority API call for each login request from a downstream relying party
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"
]
}
}
/attributes Response
The customer developed API should respond with a JSON collection when receiving a HTTP POST request. The response should have the following possible keys:
- (Required) “status” with values of either “continue” or “error”
- (Optional) “attributeMode” with values of “replace”, “merge”, “overwrite”, or “preserve”. See section on “attributeMode” behavior for details.
- (Required for “continue”) “userAttributes” should contain the attributes for the user. Values for an attribute should be an array of strings. A response without a “userAttributes” key (or set to a value of “null”) can be used to tell the Cirrus proxy to continue without altering the end user’s current attributes. A response with a “userAttributes” of an empty list will, if in replace mode, result in all of an end user’s attributes being removed.
- (Required for “error”) “message” should contain a meaningful message to the end user and can contain markdown syntax to customize the presentation of the message to the end user. Organizations may use the “error” status to guide an end user to take a prerequisite action.
“attributeMode” Parameter Behavior
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. |
Example Response #1 - Basic response
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"
]
}
}
Example Response #2 - Response with attributeMode set
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"
]
}
}
Example Response #3 - Error message
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."
}
Blog comments