On this page
SAML assertion inline hook reference
This page provides reference documentation for SAML assertion inline hooks, one type of inline hook supported by Okta. It provides sample JSON objects that are contained in the outbound request from Okta to your external service, and sample JSON objects that you can include in your response.
See also
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 a use case example of how to implement a SAML assertion inline hook, see SAML assertion inline hook.
For steps to enable this inline hook, see below, Enabling a SAML assertion inline hook.
About
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.
Objects in the request from Okta
The outbound call from Okta to your external service provides the contents of the SAML assertion that was generated, which you can 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 mapped to a JSON representation for sending.
data.assertion.subject
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"
}
}
}
}
data.assertion.authentication
Provides a JSON representation of the <saml:AuthnStatement>
element of the SAML assertion.
"authentication": {
"sessionIndex": "id1553800523546.312669168",
"authnContext": {
"authnContextClassRef": "urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport"
}
}
data.assertion.conditions
Provides a JSON representation of the <saml:Conditions>
element of the SAML assertion.
"conditions": {
"audienceRestriction": [
"urn:example:sp"
]
}
data.assertion.claims
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": {
"extPatientId": {
"attributes": {
"NameFormat": "urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"
},
"attributeValues": [
{
"attributes": {
"xsi:type": "xs:integer"
},
"value": "4321"
}
]
}
}
}
data.assertion.lifetime
Specifies the expiration time, in seconds, of the SAML assertion.
"lifetime": {
"expiration": 300
}
data.context
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 assertiondata.context.protocol
: Details of the assertion protocol being useddata.context.session
: Details of the user sessiondata.context.user
: Identifies the Okta user that the assertion was generated to authenticate and provides details of their Okta user profile
Sample listing of JSON payload of request
{
"source": "https://${yourOktaDomain}/app/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/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@example.com",
"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@example.com",
"firstName": "Admin",
"lastName": "Last",
"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@example.com",
"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": {
"extPatientId": {
"attributes": {
"NameFormat": "urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"
},
"attributeValues": [
{
"attributes": {
"xsi:type": "xs:integer"
},
"value": "4321"
}
]
},
"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": "admin"
}
]
},
"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"
}
Objects in response you send
For the SAML assertion inline hook, the objects that you can return in the JSON payload of your response are defined in the following sections.
Note: The size of your response payload must be less than 256 KB.
commands
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, you include a type
property and a value
property. The type
property is where you specify which of the supported commands you want 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 |
Supported commands
The following command is currently supported for the SAML assertion inline hook type:
Command | Description |
---|---|
com.okta.assertion.patch | Modify a SAML assertion |
value
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 | The value of the claim that you add or replace, and can also include other attributes. If adding to a claim, you need to add another value attribute residing within an array called attributeValues . See the Sample listing of JSON payload response for an example. | Any JSON object |
List of supported ops
Op | Description |
---|---|
add | Add a new claim to the assertion |
replace | Modify any element of the assertion |
Note: If a response to the SAML assertion inline hook request is not received from your external service within 3 seconds, a timeout occurs. In this scenario, the Okta process flow continues with the original SAML assertion returned.
Specify location within the assertion
Specify the location within the assertion where you want to apply your operation using a slash-delimited path, which follows JSON Patch conventions.
When you perform an add
op to add a new attribute statement, begin with /claims/
and follow that with the name of the new attribute that you are adding.
When you modify an existing assertions statement, begin the path 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, for example, /claims/array/attributeValues/1/value
. (The /1/
in the path indicates the index of the array, using zero-based indexing.)
URI claims
Okta supports URI claims with SAML assertion hooks. When you need to replace or add a URI claim, you must encode the claim name within the command per the JavaScript Object Notation (JSON) Pointer (opens new window) specification. Specifically, this replaces ~
with ~0
and /
with ~1
.
SessionNotOnOrAfter support
In some scenarios, your service provider may require the SessionNotOnOrAfter
attribute for the <saml:AuthnStatement>
in the SAML assertion, which sets the provider session time correctly. Use add
op with the path /authentication/sessionLifetime
and a value for session lifetime in seconds to add this attribute. See the Sample listing of JSON payload response for an example. Okta calculates SessionNotOnOrAfter
by adding the /authentication/sessionLifetime
value to the issueInstant
attribute and returns it in the SAML assertion.
Timeout behavior
If there is a response timeout after receiving the Okta request, the Okta process flow proceeds with the original SAML assertion returned.
Sample listing of JSON payload of response
{
"commands": [
{
"type": "com.okta.assertion.patch",
"value": [
{
"op": "replace",
"path": "/claims/array/attributeValues/1/value",
"value": "replacementValue"
},
{
"op": "replace",
"path": "/authentication/authnContext",
"value": {
"authnContextClassRef": "replacementValue"
}
},
{
"op": "add",
"path": "/claims/extPatientId",
"value": {
"attributes": {
"NameFormat": "urn:oasis:names:tc:SAML:2.0:attrname-format:basic"
},
"attributeValues": [
{
"attributes": {
"xsi:type": "xs:string"
},
"value": "4321"
}
]
}
},
{
"op": "add",
"path": "/authentication/sessionLifetime",
"value": 300
}
]
},
{
"type": "com.okta.assertion.patch",
"value": [
{
"op": "replace",
"path": "/authentication/sessionIndex",
"value": "definitelyARealSession"
}
]
}
]
}
URI format response example
This example displays replace
and add
operations with the URI formatted claim encoded.
{
"commands": [
{
"type": "com.okta.assertion.patch",
"value": [
{
"op": "replace",
"path": "/claims/http:~1~1schemas.xmlsoap.org~1ws~12005~105~1identity~1claims~1foo/attributeValues/0/value",
"value": "replacementValue"
},
{
"op": "replace",
"path": "/claims/http:~1~1schemas.xmlsoap.org~1ws~12005~105~1identity~1claims~1foo/attributes",
"value": {
"attributes": {
"NameFormat": "urn:oasis:names:tc:SAML:2.0:attrname-format:basic"
}
}
},
{
"op": "add",
"path": "/claims/http:~1~1schemas.xmlsoap.org~1ws~12005~105~1identity~1claims~1bar",
"value": {
"attributes": {
"NameFormat": "urn:oasis:names:tc:SAML:2.0:attrname-format:basic"
},
"attributeValues": [
{
"attributes": {
"xsi:type": "xs:string"
},
"value": "bearer"
}
]
}
}
]
}
]
}
Enabling a SAML assertion inline hook
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 Next to get to SAML Settings section.
Click Show Advanced Settings.
In the Assertion Inline Hook field, select your registered inline hook.
Note: You can associate only one inline hook with each app.