Home >
API >
2 >
SAML Assertions >
Generate SAML Assertion

Generate SAML Assertion

Use this API to generate a SAML assertion.

If multi-factor authentication (MFA) is enabled, this API works in close conjunction with the Verify Factor API to provide and verify the second factor.

Resource URL

https://<subdomain>/api/2/saml_assertion

Header Parameters

Authorization

required

string

Set to bearer:<access_token>.

Set <access_token> to the access token you generated using the Generate Token API.

The access token must have been generated using an API credential pair created using the scope required to call this API. This API can be called using the Authentication Only, Manage All, and Manage Users scopes.

Content-Type

required

string

Set to application/json.

Request Parameters

username_or_email

required

string

Set this to the username or email of the OneLogin user accessing the app for which you want to generate a SAML token.

password

required

string

Password of the OneLogin user accessing the app for which you want to generate a SAML token.

app_id

required

string

App ID of the app for which you want to generate a SAML token. This is the app ID in OneLogin.

subdomain

required

string

Set to the subdomain of the OneLogin user accessing the app for which you want to generate a SAML token.

For example, if your OneLogin URL is splinkly.onelogin.com, enter splinkly as the subdomain value.

ip_address

string

If you are using this API in a scenario in which MFA is required and you’ll need to be able to honor IP address whitelisting defined in MFA policies, provide this parameter and set its value to the whitelisted IP address that needs to be bypassed.

By making this a parameter that the developer passes in, the API enables you to tailor it to your use case. For example:

You are building a web app and, in this case, only the web app knows the IP address of the user accessing the application. This is the IP address that you should pass in the parameter to determine if MFA is required or should be bypassed.
You are building a native app and, in this case, only the native app knows the IP address of the machine the request is being made from. This is the IP address that you should pass in the parameter to determine if MFA is required or should be bypassed.

Sample Request Body

{
    "username_or_email": "hazel.zhang@onelogin.com",
    "password": "P@33w0rd",
    "app_id": "123456",
    "subdomain":"jha-test",
    "ip_address":"123.45.678.9"
}

Sample Response

200 OK
400 Bad Request
401 Unauthorized

{
    "data": "PHNhbWxwOlJlc3BvbnNlIHhtbG5zOnNhbWw9InVybjpvYXNpczpuYW1lczp0YzpTQU1MOjIuMDphc3NlcnRpb24iIHhtbG5zOnNhbWxwPSJ1cm46b2FzaXM6bmFtZXM6dGM6U0FNTDoyLjA6cHJvdG9jb2wiIElEPSJSZjE5Y2EyMTI0ZGMxNzJmNzhmMjI3OTk3YzMwOTBkODVkNzFjYWMzOCIgVmVyc2lvbj0iMi4wIiBJc3N1ZUluc3RhbnQ9IjIwMjAtM...",
    "message": "Success"
}


{
    "state_token": "5xxx604x8xx9x694xx860173xxx3x78x3x870x56",
    "message": "MFA is required for this user",
    "devices": [
        {
            "device_id": 666666,
            "device_type": "Google Authenticator"
        },
        {
            "device_type": "Yubico YubiKey",
            "device_id": 1111111
        }
    ],
    "callback_url": "https://subdomain.onelogin.com/api/2/saml_assertion/verify_factor",
    "user": {
        "lastname": "Zhang",
        "username": "hzhang123",
        "email": "hazel.zhang@onelogin.com",
        "firstname": "Hazel",
        "id": 88888888
    },
}

{
    "message": "MFA is required but the user has not set up any factors",
    "statusCode": 400,
    "name": "Bad Request"
}

{
    "message": "username is empty",
    "statusCode": 400,
    "name": "Bad Request"
}

{
    "message": "password is empty",
    "statusCode": 400,
    "name": "Bad Request"
}

{
    "message": "Input JSON is not valid",
    "statusCode": 400,
    "name": "Bad Request"
}

{
    "message": "Id is incorrect. It should be a positive integer",
    "statusCode": 400,
    "name": "Bad Request"
}

{
    "message": "Invalid subdomain",
    "statusCode": 401,
    "name": "Unauthorized"
}

Typically, the following error means that the password value is incorrect.

{
    "message": "Authentication Failed: Invalid user credentials",
    "statusCode": 401,
    "name": "Unauthorized"
}

Typically, the following error means that the access token is invalid.

{
    "message": "Authentication Failed",
    "statusCode": 401,
    "name": "Unauthorized"
}

{
    "message": "User is locked. Access is unauthorized",
    "statusCode": 401,
    "name": "Unauthorized"
}

Typically, the following error means that the access token used to make the call was generated using API credentials that have insufficient permissions.

{
    "message": "Insufficient Permission",
    "statusCode": 401,
    "name": "Unauthorized"
}

Response Elements

`data`	Provides the SAML assertion. Returned only when MFA is not required.
`message`	Plain text description describing the outcome of the response.
`state_token`	Provides the `state_token` value that must be submitted with each Verify Factor API call until the SAML assertion has been issued. Returned only when MFA is required.
`user`	Provides information about the user that will be logged in via the SAML assertion. `lastname` `username` `email` `firstname` `id` Returned only when MFA is required.
`devices`	Provides device values that must be submitted with the Verify Factor API call. `device_type`: Lists an available MFA device type, such as OneLogin OTP SMS or Google Authenticator. `device_id`: Lists an ID for the device type that must be submitted with the Verify Factor API call. Returned only when MFA is required.
`callback_url`	Provides the Verify Factor API endpoint to which the `device_id`, `state_token`, `app_id`, and `otp_token` must be sent for verification. Returned only when MFA is required.

Postman Collection

Replace sample variables indicated by < > in the sample request body with your actual values. Also, be sure to set Postman-specific environment variables indicated by {{ }}.

Download for the SAML Assertion API

Sample cURL Request

Replace sample values indicated by < > with your actual values.

curl "https://<subdomain>/api/2/saml_assertion" \
-X POST \
-H "Authorization: bearer:<access_token>" \
-H "Content-Type: application/json" \
-d '{
    "username_or_email": "<username_or_email>",
    "password": "<password>",
    "app_id": "<app_id>",
    "subdomain":"<subdomain>",
    "ip_address":"<ip_address>"
}'

Have a Question?

Found a problem or a bug? Submit a support ticket.

Looking for walkthroughs or how-to guides on OneLogin's user and admin features? Check out the documentation in our Knowledge Base.

Have a product idea or request? Share it with us in our Ideas Portal.