This page provides reference documentation for:
JSON objects contained in the outbound request from Okta to your external service
JSON objects you can include in your response
This information is specific to the SAML Assertion Inline Hook, one type of inline hook supported by Okta.
For a general introduction to Okta inline hooks, see Inline Hooks.
For information on the API for registering external service endpoints with Okta, see Inline Hooks Management API.
For steps to enable this inline hook, see below, Enabling a SAML Assertion Inline Hook.
This type of inline hook is triggered when Okta generates a SAML assertion in response to an authentication request. Before sending the SAML assertion to the app that will consume it, Okta calls out to your external service. Your external service can respond with commands to add attributes to the assertion or to modify its existing attributes.
This functionality can be used to add data to assertions, which might be data that is sensitive, calculated at runtime, or complexly-structured and not appropriate for storing in Okta user profiles. Data added this way is never logged or stored by Okta. As an example, SAML assertions generated for a medical app could be augmented with confidential patient data provided by your external service and not stored in Okta.
This inline hook works only when using custom SAML apps, not apps from the OIN.
The outbound call from Okta to your external service provides you with the contents of the SAML assertion that was generated, which you will be able to augment or modify by means of the commands you return. Also provided is contextual information about the authentication request.
Because SAML is XML-based, but the call from Okta to your service uses a JSON payload, the contents of the SAML assertion are converted to a JSON representation for sending.
Provides a JSON representation of the <saml:Subject> element of the SAML assertion. The following is an example of how the SAML XML is represented in JSON:
{
"subject":{
"nameId":"administrator1@example.net",
"nameFormat":"urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified",
"confirmation":{
"method":"urn:oasis:names:tc:SAML:2.0:cm:bearer",
"data":{
"recipient":"http://www.example.com/saml/sso"
}
}
}
}
Provides a JSON representation of the <saml:AuthnStatement> element of the SAML assertion.
Provides a JSON representation of the <saml:Conditions> element of the SAML assertion.
Provides a JSON representation of the <saml:AttributeStatement> element contained in the generated SAML assertion, which will contain any optional SAML attribute statements that you have defined for the app using the Okta Admin Console's SAML Settings.
The following is an example of how an XML <saml:AttributeStatement> element is represented in JSON in this object:
{
"claims": {
"foobie": {
"attributes": {
"NameFormat": "urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"
},
"attributeValues": [
{
"attributes": {
"xsi:type": "xs:string"
},
"value": "doobie"
}
]
}
}
}
Specifies the expiration time, in seconds, of the SAML assertion.
This object contains a number of sub-objects, each of which provides some type of contextual information. Unlike the data.assertion.* objects, you cannot affect the data.context.* objects by means of the commands you return.
The following sub-objects are included:
data.context.request: Details of the SAML request that triggered the generation of the SAML assertion.data.context.protocol: Details of the assertion protocol being used.data.context.session: Details of the user session.data.context.user: Identifies the Okta user that the assertion was generated to authenticate, and provides details of their Okta user profile.For the SAML Assertion Inline Hook, the objects you can return in the JSON payload of your response are defined as follows:
The commands object is where you can tell Okta to add additional claims to the assertion or to modify the existing assertion statements.
commands is an array, allowing you to send multiple commands. In each array element, there needs to be a type property and value property. The type property is where you specify which of the supported commands you wish to execute, and value is where you supply an operand for that command.
In the case of the SAML Assertion Inline Hook, the value property is itself a nested object, in which you specify a particular operation, a path to act on, and a value.
| Property | Description | Data Type |
|---|---|---|
| type | One of the supported commands. | String |
| value | Operand to pass to the command. It specifies a particular op to perform. | value |
The following command is currently supported for the SAML Assertion Inline Hook type:
| Command | Description |
|---|---|
| com.okta.assertion.patch | Modify a SAML assertion. |
The value object is where you specify the specific operation to perform. It is an array, allowing you to request more than one operation.
| Property | Description | Data Type |
|---|---|---|
| op | The name of one of the supported ops. | String |
| path | Location, within the assertion, to apply the operation. See Specifying Location within the Assertion below. | String |
| value | Value to set the claim to. | Any JSON object |
| Op | Description |
|---|---|
| add | Add a new claim to the assertion. |
| replace | Modify an existing attribute statement. |
You specify the location within the assertion at which to apply your operation using a slash-delimited path.
When performing an add op to add a new attribute statement, this will always begin with /claims/ and be followed by the name of the new attribute you are adding.
When modifying an existing assertions statement, the path could begin with /subject/, /authentication/, /conditions/, or /claims/, depending on which part of the assertion you want to modify. You then drill down within the child elements using slash-delimited element names, e.g., /claims/array/attributeValues/1/value.
{
"source": "https://{yourOktaDomain}/app/raincloud59_saml20app_1/exkth8lMzFm0HZOTU0g3/sso/saml",
"eventId": "XMFoHCM1S4Wi_SGWzL8T9A",
"eventTime": "2019-03-28T19:15:23.000Z",
"data": {
"context": {
"request": {
"id": "reqqXypjzYJRSu2j1G1imUovA",
"method": "GET",
"url": {
"value": "https://{yourOktaDomain}/app/raincloud59_saml20app_1/exkth8lMzFm0HZOTU0g3/sso/saml"
},
"ipAddress": "127.0.0.1"
},
"protocol": {
"type": "SAML2.0",
"issuer": {
"id": "0oath92zlO60urQOP0g3",
"name": "SAML 2.0 App",
"uri": "http://www.okta.com/exkth8lMzFm0HZOTU0g3"
}
},
"session": {
"id": "102LN9Bnuc4S_ewfc9BYwageA",
"userId": "00uq8tMo3zV0OfJON0g3",
"login": "administrator1@clouditude.net",
"createdAt": "2019-03-28T16:45:55.000Z",
"expiresAt": "2019-03-28T21:15:23.000Z",
"status": "ACTIVE",
"lastPasswordVerification": "2019-03-28T16:45:55.000Z",
"amr": [
"PASSWORD"
],
"idp": {
"id": "00oq6kcVwvrDY2YsS0g3",
"type": "OKTA"
},
"mfaActive": false
},
"user": {
"id": "00uq8tMo3zV0OfJON0g3",
"passwordChanged": "2018-09-11T23:19:12.000Z",
"profile": {
"login": "administrator1@clouditude.net",
"firstName": "Add-Mine",
"lastName": "O'Cloudy Tud",
"locale": "en",
"timeZone": "America/Los_Angeles"
},
"_links": {
"groups": {
"href": "https://{yourOktaDomain}/00uq8tMo3zV0OfJON0g3/groups"
},
"factors": {
"href": "https://{yourOktaDomain}/api/v1/users/00uq8tMo3zV0OfJON0g3/factors"
}
}
}
},
"assertion": {
"subject": {
"nameId": "administrator1@clouditude.net",
"nameFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified",
"confirmation": {
"method": "urn:oasis:names:tc:SAML:2.0:cm:bearer",
"data": {
"recipient": "http://www.example.com:7070/saml/sso"
}
}
},
"authentication": {
"sessionIndex": "id1553800523546.312669168",
"authnContext": {
"authnContextClassRef": "urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport"
}
},
"conditions": {
"audienceRestriction": [
"urn:example:sp"
]
},
"claims": {
"foobie": {
"attributes": {
"NameFormat": "urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"
},
"attributeValues": [
{
"attributes": {
"xsi:type": "xs:string"
},
"value": "doobie"
}
]
},
"array": {
"attributes": {
"NameFormat": "urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"
},
"attributeValues": [
{
"attributes": {
"xsi:type": "xs:string"
},
"value": "Array 1"
},
{
"attributes": {
"xsi:type": "xs:string"
},
"value": "Array2"
},
{
"attributes": {
"xsi:type": "xs:string"
},
"value": "Array3"
}
]
},
"middle": {
"attributes": {
"NameFormat": "urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"
},
"attributeValues": [
{
"attributes": {
"xsi:type": "xs:string"
},
"value": "middellllll"
}
]
},
"firstAndLast": {
"attributes": {
"NameFormat": "urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"
},
"attributeValues": [
{
"attributes": {
"xsi:type": "xs:string"
},
"value": "7d6a50c8-4d7e-4058-9c5b-2cc98cecd294"
}
]
}
},
"lifetime": {
"expiration": 300
}
}
},
"eventTypeVersion": "1.0",
"cloudEventVersion": "0.1",
"eventType": "com.okta.saml.tokens.transform",
"contentType": "application/json"
}
{
"commands": [
{
"type": "com.okta.assertion.patch",
"value": [
{
"op": "replace",
"path": "/claims/array/attributeValues/1/value",
"value": "replacementValue"
},
{
"op": "replace",
"path": "/authentication/authnContext",
"value": {
"authnContextClassRef": "Something:different?"
}
},
{
"op": "add",
"path": "/claims/foo",
"value": {
"attributes": {
"NameFormat": "urn:oasis:names:tc:SAML:2.0:attrname-format:basic"
},
"attributeValues": [
{
"attributes": {
"xsi:type": "xs:string"
},
"value": "barer"
}
]
}
}
]
},
{
"type": "com.okta.assertion.patch",
"value": [
{
"op": "replace",
"path": "/authentication/sessionIndex",
"value": "definitelyARealSession"
}
]
}
]
}
To activate the inline hook, you first need to register your external service endpoint with Okta using the Inline Hooks Management API.
You then need to associate the registered inline hook with a SAML app by completing the following steps in Admin Console:
Go to Applications and select your SAML app.
Click the General tab.
In the SAML Settings section, click Edit.
Click Show Advanced Settings.
Click Next to get to the Configure SAML section.
In the Assertion Inline Hook field, select your registered inline hook.
Note: Only one inline hook can be associated with each app.