See api-docs Menu

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://api.<us_or_eu>.onelogin.com/api/1/
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

{
    "status": {
        "type": "success",
        "message": "Success",
        "error": false,
        "code": 200 
    },
   "data": "PHNhbWxwOlJlc3BvbnNlIHhtbG5zOnNhbWw9InVybjpvYXNpczpuYW1lczp0YzpTQU1MOjIuMDphc
            3NlcnRpb24iIHhtbG5zOnNhbWxwPSJ1cm46b2FzaXM6bmFtZXM6dGM6U0FNTDoyLjA6cHJvdG9jb2
            wiIElEPSJSZDkwYTY5NDg1YTdiMmMxYjM0NWFjOGQ1Y2UyZmExMzFkZmRkMzRlOSIgVmVyc2lvbj0
            iMi4wIiBJc3N1ZUluc3RhbnQ9IjIwMTYtMDMtMTdUMjI6NTA6MzBaIiBEZXN0aW5hdGlvbj0iaHR0
            cHM6Ly97c3ViZG9tYWlufS5mYWNlYm9vay5jb20vd29yay9zYW1sLnBocCI+P..."
}

{
    "status": {
        "type": "success",
        "message": "MFA is required for this user",
        "code": 200,
        "error": false
    },
    "data": [
        {
            "state_token": "5xxx604x8xx9x694xx860173xxx3x78x3x870x56",
            "devices": [
                {
                    "device_id": 666666,
                    "device_type": "Google Authenticator"
                }
            ],
            "callback_url": "https://api.us.onelogin.com/api/1/saml_assertion/
                             verify_factor",
            "user": {
                "lastname": "Zhang",
                "username": "hzhang123",
                "email": "hazel.zhang@onelogin.com",
                "firstname": "Hazel",
                "id": 88888888
            },
        }
    ]
}

{
  "status": {
    "type": "pending",
    "message": "SMS token sent to your mobile device. Authentication pending.",
    "error": false,
    "code": 200
  }
}
{
    "status": {
        "type": "bad request",
        "code": 400,
        "message": "MFA is required but the user has not set up any factors",
        "error": true
    }
}

{
    "status": {
        "error": true,
        "code": 400,
        "type": "bad request",
        "message": "Authorization Information is incorrect"
    }
}

{
    "status": {
        "type": "error",
        "message": "username is empty",
        "error": true,
        "code": 400
    }
}

{
    "status": {
        "type": "error",
        "message": "password is empty",
        "code": 400,
        "error": true
    }
}

{
    "status": {
        "error": true,
        "code": 400,
        "type": "bad request",
        "message": "Input JSON is not valid"
    }
}

{
    "status": {
        "type": "bad request",
        "message": "Id is incorrect. It should be a positive integer",
        "error": true,
        "code": 400
    }
}

Typically, the following error means that you have not included the required subdomain value in the request body.

{
    "status": {
        "type": "Unauthorized",
        "message": "Authentication Failed",
        "error": true,
        "code": 401
    }
}

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

{
    "status": {
        "type": "Unauthorized",
        "message": "Authentication Failed: Invalid user credentials",
        "error": true,
        "code": 401
    }
}

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

{
    "status": {
        "error": true,
        "code": 401,
        "type": "Unauthorized",
        "message": "Authentication Failure"
    }
}

{
    "status": {
        "type": "Unauthorized",
        "message": "User is locked. Access is unauthorized",
        "code": 401,
        "error": true
    }
}

{
    "status": {
        "type": "Unauthorized",
        "message": "Invalid subdomain",
        "code": 401,
        "error": true
    }
}

Typically, the following error means that the access token used to make the call was generated using API credentials that have insufficient permissions. This API can be called using the Manage All scope only.

{
    "status": {
        "error": true,
        "code": 401,
        "type": "Unauthorized",
        "message": "Insufficient Permission"
    }
}

Response Elements

data

Provides the SAML assertion.

Returned only when MFA is not required.

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://api.<us_or_eu>.onelogin.com/api/1/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?

Have a how-to question? Seeing a weird error? Ask us about it on StackOverflow.

Found a bug? Submit a support ticket.

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