Home >
API >
1 >
SAML Assertions >
Generate SAML Assertion

Generate SAML Assertion

Deprecated

This version is deprecated and will be removed in February 2021.

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

Before calling this API, consider using its version /2 equivalent.

https://<subdomain>/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 allow-listing defined in MFA policies, provide this parameter and set its value to the allowed 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

{
    "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://subdomain.onelogin.com/api/1/saml_assertion/
                             verify_factor",
            "user": {
                "lastname": "Zhang",
                "username": "hzhang123",
                "email": "hazel.zhang@onelogin.com",
                "firstname": "Hazel",
                "id": 88888888
            },
        }
    ]
}

{
    "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.

{
    "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

Clicking Run in Postman button navigates to the page where you can fork the collection to your workspace. Forking the collection into your workspace will enable you to contribute to the source collection using pull requests. You can also view the collection in a public workspace if you like and even import a copy of the collection using the links present on the screen.

Sample cURL Request

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

curl "https://<subdomain>/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>"
}'

/?tags=onelogin+saml+api” target=”_blank”>StackOverflow.