POST

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>.onelogin.com/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 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

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

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

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

</div>
</div>


## Response Elements
<table width="100%" border="0" cellpadding="10">
  <tbody>
      <tr>
      <td valign="top" style="text-align: right"><code>data</code></td>
      <td><p>Provides the SAML assertion.</p>
      <p>Returned only when MFA is not required.</p></td>
    </tr>
    <tr>
      <td valign="top" style="text-align: right"><code>message</code></td>
      <td><p>Plain text description describing the outcome of the response.</p></td>
    </tr>
    <tr>
      <td width="20%" valign="top" style="text-align: right"><code>state_token</code></td>
      <td><p>Provides the<code> state_token</code> value that must be submitted with each <a href="/api-docs/2/saml-assertions/verify-factor" data-sidebar="verify-factor-1">Verify Factor</a> API call until the SAML assertion has been issued.</p>
        <p>Returned only when MFA is required.</p></td>
    </tr>
    <tr>
      <td valign="top" style="text-align: right"><code>user</code></td>
      <td><p>Provides information about the user that will be logged in via the SAML assertion.</p>
        <ul>
          <li><code>lastname</code></li>
          <li><code>username</code></li>
          <li><code>email</code></li>
          <li><code>firstname</code></li>
          <li><code>id</code></li>
      </ul>
      <p>Returned only when MFA is required.</p></td>
    </tr>
    <tr>
      <td valign="top" style="text-align: right"><code>devices</code></td>
      <td><p>Provides device values that must be submitted with the <a href="/api-docs/2/saml-assertions/verify-factor" data-sidebar="verify-factor-1">Verify Factor</a> API call.</p>
        <ul>
          <li>
            <p><code>device_type</code>: Lists an available MFA device type, such as OneLogin OTP SMS or Google Authenticator.</p>
          </li>
          <li>
            <p><code>device_id</code>: Lists an ID for the device type that must be submitted with the <a href="/api-docs/2/saml-assertions/verify-factor" data-sidebar="verify-factor-1">Verify Factor </a>API call.</p>

          </li>
      </ul><p>Returned only when MFA is required.</p></td>
    </tr>
    <tr>
      <td valign="top" style="text-align: right"><code>callback_url</code></td>
      <td><p>Provides the <a href="/api-docs/2/saml-assertions/verify-factor" data-sidebar="verify-factor-1">Verify Factor</a> API endpoint to which the <code>device_id</code>, <code>state_token</code>, <code>app_id</code>, and <code>otp_token</code> must be sent for verification.</p>
      <p>Returned only when MFA is required.</p></td>
    </tr>
  </tbody>
</table>

## Postman Collection

[<img src=https://run.pstmn.io/button.svg alt="Run In Postman" style="width: 128px; height: 32px;">](https://god.gw.postman.com/run-collection/2629710-1cf1fce8-800e-43af-9d4a-8ed5f631125e?action=collection%2Ffork&source=rip_markdown&collection-url=entityId%3D2629710-1cf1fce8-800e-43af-9d4a-8ed5f631125e%26entityType%3Dcollection%26workspaceId%3D2a9bbc3a-4259-4faf-9f51-0b7ca1df3fd0)

## Sample cURL Request
Replace sample values indicated by `< >` with your actual values.

```bash
curl "https://<subdomain>.onelogin.com/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>"
}'