Single Sign On Configuration

Permissions

Permission	Manageable via Roles	Description
list	true	Allow list SSO configurations
view	true	Allow view single SSO configuration details
create	true	Allow create SSO configurations
edit	true	Allow edit SSO configurations
delete	true	Allow delete SSO configurations

Permissions for SSO Config can be checked by:

Context	Endpoint	Location	Available perms
Global scope	`GET /api/users/permissions/`	`single_sign_on`	`list`, `view`, `edit`, `create`, `delete`
Specific single_sign_on	`GET /api/single-sign-on/{id}/`	`_meta.permissions`	`list`, `view`, `edit`, `create`, `delete`

References

SSO Technical Design

POST /api/single-sign-on/

Creates Single Sign On Configuration.

Permissions

Requires authentication and single_sign_on.create permission.

Request

Body parameters

Key	Type	Notes
name	string	Displayed name
client_id	string	Client ID
tenant_id	string	Provider specific: Azure: Azure tenant identifier Okta: Okta tenant (organization) domain (for example, acme.okta.com)
provider	enum	Provider (one of `azure`, `okta`)
is_enabled	bool	Enabled flag
auto_create_user	bool	If should create user when it does not exists
roles	enum	Attached roles ID's after create user
*is_word_addin_enabled	bool	If configuration supports Word Addin (optional)

Headers

Content-Type: application/json
Authorization: JWT access_token

Schema

json

POST /api/single-sign-on/ 

{
  "name": <string>,
  "client_id":  <string>,  
  "client_secret":  <string>, 
  "tenant_id":  <string>,  
  "provider":  <string>,  
  "is_enabled": <bool>,  
  "auto_create_user":  <bool>, 
  "roles":  <enum>,  
  "is_word_addin_enabled": <bool>
}

Validations

Max 25 objects
name
- Max length: 100
- Case insensitive unique
client_id
- Max length: 255
- [a-zA-Z0-9-]
client_secret
- Max length: 255
- [a-zA-Z0-9-]
tenant_id
- Max length: 255
- [a-zA-Z0-9-]
providers
- one of (azure, okta)
is_word_addin_enabled
- only with provider = azure
- only one per each azure application SSO, with set as True. Only one Azure application SSO with the same client_id and tenant_id can have is_word_addin_enabled set as True.

Response

Key	Type	Notes
id	id	Automatically generated by the backend.
name	string	Displayed name
client_id	string	Client ID
tenant_id	string	Provider specific: Azure: Azure tenant identifier Okta: Okta tenant (organization) domain (for example, acme.okta.com)
provider	enum	Provider (one of `azure`, `okta`)
is_enabled	bool	Enabled flag
auto_create_user	bool	If should create user when it does not exists
is_word_addin_enabled	enum	If configuration supports Word Addin
roles	enum	Attached roles ID's after create user
redirect_uri	url	Login callback URL
created_at	datetime
created_by	user
modified_at	datetime
modified_by	user
logout_url	url	Logout callback URL
_meta.labels	Object	Object containing labels for attributes.
_meta.permissions	Object	Object describing permissions.

Successful status 201 Created
Response body schema

json

{  
   "id": <int>,  
   "name": <string>, 
   "client_id": <string>, 
   "tenant_id": <string>, 
   "is_enabled": <bool>,  
   "is_word_addin_enabled": <bool>,  
   "auto_create_user": <bool>,  
   "roles": <enum>,  
   "provider": <string>,  
   "redirect_uri": <url>, 
   "created_at": <datetime>,  
   "created_by": <user>, 
   "modified_at": <datetime>,  
   "modified_by": <user>,
   "logout_url": <url>, 
  "_meta": { 
      "labels": { 
          "roles": <enum> 
      }, 
      "permissions": <set> 
  } 
}

Errors

Cause	Response code	Message
Using is_word_addin_enabled param when provider is not azure	400 Bad Request	"is_word_addin_enabled": "Provider must be "azure"."
Max 25 SSO Config exceeded	400 Bad Request	"detail": ["Limit of 25 SSO configurations has been exceeded."]

GET /api/single-sign-on/

Returns list of Single Sign On Configurations.

Permissions

Requires authentication and single_sign_on.list permission.

Request

Headers

Content-Type: application/json
Authorization: JWT access_token

Schema

json

GET /api/single-sign-on/

Response

Key	Type	Notes
limit	int
offset	int
total_count	int	Total number of results visible to the user (based on permissions).
filtered_count	int	Number of results visible to the user (based on permissions) with filters applied.
next	url	Next page URL (null if there is no next page)
previous	url	Previous page URL (null if there is no previous page)
results	Array	List of results. Described in the next table.

Response `results` array

Key	Type	Notes
id	id	Automatically generated by the backend.
name	string	Displayed name
client_id	string	Client ID
tenant_id	string	Provider specific: Azure: Azure tenant identifier Okta: Okta tenant (organization) domain (for example, acme.okta.com)
provider	enum	Provider (one of `azure`)
is_enabled	bool	Enabled flag
auto_create_user	bool	If should create user when it does not exists
is_word_addin_enabled	enum	If configuration supports Word Addin
roles	enum	Attached roles ID's after create user
created_at	datetime
created_by	user
modified_at	datetime
modified_by	user
_meta.labels	Object	Object containing labels for attributes.
_meta.permissions	Object	Object describing permissions.

Successful status 200 OK
Response body schema

json

{
   "limit": <int>,  
   "offset": <int>,  
   "filtered_count": <int>,  
   "total_count": <int>,  
   "next": <url>,  
   "previous": <url>,  
   "results": [
     {
       "id": <int>,
       "name": <string>,
       "client_id": <string>,
       "tenant_id": <string>,
       "is_enabled": <bool>,
       "is_word_addin_enabled": <string>,
       "auto_create_user": <bool>,
       "roles": <enum>,
       "provider": <string>,
       "redirect_uri": <url>,
       "created_at": <datetime>,
       "created_by": <user>,
       "modified_at": <datetime>,
       "modified_by": <user>,
       "_meta": {
         "labels": {
           "roles": <enum>
         },
         "permissions": <set>
       }
     }
   ]
}

Sorting

Parameter	Example	Notes
id	/{%endpoint%}/?ordering=id	Ascending
id	/{%endpoint%}/?ordering=-id	Descending (-)
name	/{%endpoint%}/?ordering=name	Ascending
name	/{%endpoint%}/?ordering=-name	Descending (-)
created_at	/{%endpoint%}/?ordering=created_at	Ascending
created_at	/{%endpoint%}/?ordering=-created_at	Descending (-)
modified_at	/{%endpoint%}/?ordering=modified_at	Ascending
modified_at	/{%endpoint%}/?ordering=-modified_at	Descending (-)

Filtering

Please check ALX API standards for predicates available per type.

Parameter	Type
id	int
name	string
provider	enum
is_enabled	bool
auto_create_user	bool
is_word_addin_enabled	bool
created_at	datetime
created_by	user
modified_at	datetime
modified_by	user

Errors

Error	Response code	Message
Wrong ordering value	400 Bad Request	"ordering": ["Select a valid choice. {value} is not one of the available choices."]

GET /api/single-sign-on/ `id`/

Returns single SSO Config by id.

Permissions

Requires authentication and single_sign_on.view permission.

Request

URL parameters

Key	Type	Notes
id	int

Headers

Content-Type: application/json
Authorization: JWT access_token

Schema

json

GET /api/single-sign-on/ `id`/

Response

Key	Type	Notes
id	id	Automatically generated by the backend.
name	string	Displayed name
client_id	string	Client ID
tenant_id	string	Provider specific: Azure: Azure tenant identifier Okta: Okta tenant (organization) domain (for example, acme.okta.com)
provider	enum	Provider (one of `azure`)
is_enabled	bool	Enabled flag
auto_create_user	bool	If should create user when it does not exists
is_word_addin_enabled	enum	If configuration supports Word Addin
roles	enum	Attached roles ID's after create user
redirect_uri	url	Login callback URL
created_at	datetime
created_by	user
modified_at	datetime
logout_url	url	Logout callback URL
_meta.labels	Object	Object containing labels for attributes.
_meta.permissions	Object	Object describing permissions.

Successful status 200 OK
Response body schema:

json

{
  "id": <int>,  
   "name": <string>, 
   "client_id": <string>, 
   "tenant_id": <string>, 
   "is_enabled": <bool>,  
   "is_word_addin_enabled": <bool>,  
   "auto_create_user": <bool>,  
   "roles": <enum>,  
   "provider": <string>,  
   "redirect_uri": <url>, 
   "created_at": <datetime>,  
   "created_by": <user>, 
   "modified_at": <datetime>,  
   "modified_by": <user>, 
   "logout_url": <url>, 
  "_meta": { 
      "labels": { 
          "roles": <enum> 
      }, 
      "permissions": <set> 
  } 
}

Errors

Error	Response code	Message
Insufficient permissions	403 Forbidden	"detail": "You do not have permission to perform this action."
SSO Config with "id" does not exist	404 Not Found	"detail": "Not found."

PATCH /api/single-sign-on/ `id`/

Updates single SSO Config.

Permissions

Requires authentication and single_sign_on.edit permission.

Request

URL parameters

Key	Type	Notes
id	int

Body parameters

Key	Type	Notes
name	string	Displayed name
client_id	string	Client ID
tenant_id	string	Provider specific: Azure: Azure tenant identifier Okta: Okta tenant (organization) domain (for example, acme.okta.com)
is_enabled	bool	Enabled flag
auto_create_user	bool	If should create user when it does not exists
roles	enum	Attached roles ID's after create user
is_word_addin_enabled	enum	If configuration supports Word Addin

Headers

Content-Type: application/json
Authorization: JWT access_token

Schema

json

PATCH /api/single-sign-on/ `id`/

{
  "name": <string>,
  "client_id":  <string>,  
  "client_secret":  <string>, 
  "tenant_id":  <string>,  
  "is_enabled": <bool>,  
  "auto_create_user":  <bool>, 
  "roles":  <enum>,  
  "is_word_addin_enabled": <bool>
  ...
}

Response

Key	Type	Notes
id	id	Automatically generated by the backend.
name	string	Displayed name
client_id	string	Client ID
tenant_id	string	Provider specific: Azure: Azure tenant identifier Okta: Okta tenant (organization) domain (for example, acme.okta.com)
provider	enum	Provider (one of `azure`)
is_enabled	bool	Enabled flag
auto_create_user	bool	If should create user when it does not exists
is_word_addin_enabled	enum	If configuration supports Word Addin
roles	enum	Attached roles ID's after create user
redirect_uri	url	Login callback URL
created_at	datetime
created_by	user
modified_at	datetime
modified_by	user
logout_url	url	Logout callback URL
_meta.labels	Object	Object containing labels for attributes.
_meta.permissions	Object	Object describing permissions.

Successful status 200 OK
Response body schema:

json

{
   "id": <int>,  
   "name": <string>, 
   "client_id": <string>, 
   "tenant_id": <string>, 
   "is_enabled": <bool>,  
   "is_word_addin_enabled": <bool>,  
   "auto_create_user": <bool>,  
   "roles": <enum>,  
   "provider": <string>,  
   "redirect_uri": <url>, 
   "created_at": <datetime>,  
   "created_by": <user>, 
   "modified_at": <datetime>,  
   "modified_by": <user>, 
   "logout_url": <url>, 
  "_meta": { 
      "labels": { 
          "roles": <enum> 
      }, 
      "permissions": <set> 
  } 
}

Errors

Cause	Response code	Message
Using is_word_addin_enabled param when provider is not azure	400 Bad Request	"is_word_addin_enabled": "Provider must be "azure"."

DELETE /api/single-sign-on/`id`/

Deletes single SSO Config.

Permissions

Requires authentication and single_sign_on.delete permission.

Request

URL parameters

Key	Type	Notes
id	int

Headers

Content-Type: application/json
Authorization: JWT access_token

Schema

json

DELETE /api/single-sign-on/`id`/

Response

Successful status 204 No Content

OPTIONS /api/single-sign-on/

Permissions

Requires authentication only.

Request

Headers

Content-Type: application/json
Authorization: JWT access_token

Schema

json

OPTIONS /api/single-sign-on/

Response

Successful status 200 OK
Response body:

json

{
  "list": {  
        "columns": [  
            {  
                "alias": "id",  
                "type": "int",  
                "predicates": [  
                    "exact",  
                    "gt",  
                    "gte",  
                    "lt",  
                    "lte",  
                    "range"  
                ],  
                "sort_ok": false  
            },  
            {  
                "alias": "name",  
                "type": "string",  
                "predicates": [  
                    "exact",  
                    "iexact",  
                    "contains",  
                    "icontains",  
                    "startswith",  
                    "istartswith",  
                    "endswith",  
                    "iendswith"  
                ],  
                "sort_ok": true  
            },  
            {  
                "alias": "provider",  
                "type": "enum",  
                  "predicates": [  
                    "exact",  
                    "in"  
                ],  
                "sort_ok": false,  
                "values": [  
                    {  
                        "value": "azure",  
                        "text": "Microsoft Azure"  
                    },
                    {
                        "value": "okta",
                        "text": "Okta" 
                    }
                ] 
            },  
            {  
                "alias": "is_enabled",  
                "type": "boolean",  
                "predicates": ["exact"],  
                "sort_ok": false  
            },
            {  
                "alias": "is_word_addin_enabled",  
                "type": "boolean",  
                "predicates": ["exact"],  
                "sort_ok": false  
            },
            {  
                "alias": "auto_create_user",  
                "type": "boolean",  
                "predicates": ["exact"],  
     
                "sort_ok": false  
            },  
            {  
                "alias": "created_at",  
                "type": "datetime",  
                "predicates": [  
                    "exact",  
                    "gt",  
                    "gte",  
                    "lt",  
                    "lte",  
                    "range"  
                ],  
                "sort_ok": true  
            },  
            {  
                "alias": "created_by",  
                "type": "enum",  
                "predicates": [  
                    "exact",  
                    "in"  
                ],  
                "sort_ok": false,  
                "autocomplete": "/api/users/autocomplete/?text__icontains="  
            },  
            {  
                "alias": "modified_at",  
                "type": "datetime",  
                "predicates": [  
                    "exact",  
                    "gt",  
                    "gte",  
                    "lt",  
                    "lte",  
                    "range"  
                ],  
                "sort_ok": true  
            },  
            {  
                "alias": "modified_by",  
                "type": "enum",  
                "predicates": [  
                    "exact",  
                    "in"  
                ],  
                "sort_ok": false,  
                "autocomplete": "/api/users/autocomplete/?text__icontains="  
            }  
        ]  
    },  
    "details": {  
        "schema": [  
            {  
                "alias": "name",  
                "type": "string",  
                "required": true,  
                "validators": [  
                    {  
                        "type": "max_length",  
                        "length": 100  
                    }  
                ]  
            },  
            {  
                "alias": "provider",  
                "type": "enum",  
                "required": true,  
                "values": [  
                    {  
                        "value": "azure",  
                        "text": "Microsoft Azure"  
                    },
                    {
                      "value": "okta",
                      "text": "Okta" 
                    }
                ]  
            }, 
            {  
                "alias": "client_id",  
                "type": "string",  
                "required": true,  
                "validators": [  
                    {  
                        "type": "max_length",  
                        "length": 256  
                    }  
                ]  
            },  
            {  
                "alias": "client_secret",  
                "type": "string",  
                "required": true,  
                "validators": [  
                    {  
                        "type": "max_length",  
                        "length": 256  
                    }  
                ]  
            },  
            {  
                "alias": "tenant_id",  
                "type": "string",  
                "required": true,  
                "validators": [  
                    {  
                        "type": "max_length",  
                        "length": 256  
                    }  
                ]  
            },  
            {  
                "alias": "is_enabled",  
                "type": "bool",  
                "required": false  
            },
            {
                "alias": "is_word_addin_enabled",  
                "type": "bool",  
                "required": false  
            },
            {  
                "alias": "auto_create_user",  
                "type": "bool",  
                "required": false  
            },  
            {  
                "alias": "roles",  
                "type": "set",  
                "required": false,  
                "autocomplete": "/api/roles/autocomp?text__icontains=",  
                "validators": [  
                    {  
                        "type": "max_items",  
                        "items": 10  
                    }  
                ] 
            }  
        ]  
    },  
    "restrictions": {  
        "limit_items": 25  
    }
}

Retrieve provider authorization url.

Permissions

Public access endpoint.

Request

Body parameters

Key	Type	Notes
id	int

Headers

Content-Type: application/json

Schema

POST /api/single-sign-on/login/

json

{
  "id": <int>,
}

Response

Key	Type	Notes
redirect_uri	url

Successful status 200 OK
Response body:

json

{ 
    "redirect_uri": "https://example-tenant.okta.com/oauth2/default/v1/authorize?client_id=YOUR_CLIENT_ID&response_type=code&scope=openid+profile+email&response_mode=query&token_endpoint_auth_method=client_secret_post&redirect_uri=https%3A%2F%2Fyour-app-domain.com%2Fsingle-sign-on%2Fcallback%2F1%2F&state=EXAMPLE_STATE_TOKEN"
}

Errors

Cause	Response code	Message
No id in request	400 Bad Request	"detail": {"id":["This field is required."]}
No request body	400 Bad Request	"detail": {"id":["This field is required."]}
Wrong type of data	400 Bad Request	"detail": Invalid data. Expected a dictionary, but got str.
Invalid `id` in URL	404 Not Found	"detail": ["Not found."]

POST /api/single-sign-on/callback/`id`/

Retrieve the access and refresh tokens.

Permissions

Public access endpoint is secured only with an SSO state parameter (CSRF protection only).

Request

Body parameters

Key	Type	Notes
id	int
code	string	A temporary authorization code received from Okta that will be exchanged for an access token. Valid for a short time period and can only be used once when exchange it for tokens.
state	string	An arbitrary alphanumeric string that the authorization server reproduces when redirecting the user agent back to the client. authorization parameters. This is used to help prevent cross-site request forgery. (optional)
session_state	string	Session State. JSON [RFC7159] string that represents the End-User's login state at the OP. This value is opaque to the RP. authorization parameters. This is REQUIRED if session management is supported. (optional)

Headers

Content-Type: application/json

Schema

POST /api/single-sign-on/callback/id/

json

{
  "code": <string>,
  "state": <string>,  
  "session_state": <string>,
}

Response

Key	Type	Notes
refresh	string
access	string

Successful status 200 OK
Response body:

json

{ 
    "refresh": "REFRESH_TOKEN", 
    "access": "ACCESS_TOKEN"
}

Errors

Cause	Response code	Message
no code in request	400 Bad Request	"detail": {"code": ["This field is required."]}
One of parameters is blank	400 Bad Request	"detail": { "field": ["This field may not be blank."]}
One of parameters is null	400 Bad Request	"detail": { "field": ["This field may not be null."]}
Insufficient data, invalid code etc.	403 Forbidden	"detail": "You do not have permission to perform this action."
Login not allowed for account type restricted to password login only	403 Forbidden	"detail": "This user account is not allowed to log in using Single Sign-On."
Invalid `id` in URL	404 Not Found	"detail": ["Not found."]

Single Sign On Configuration ​

Permissions ​

References ​

POST /api/single-sign-on/ ​

Permissions ​

Request ​

Validations ​

Response ​

Errors ​

GET /api/single-sign-on/ ​

Permissions ​

Request ​

Response ​

Response results array ​

Sorting ​

Filtering ​

Errors ​

GET /api/single-sign-on/ id/ ​

Permissions ​

Request ​

Response ​

Errors ​

PATCH /api/single-sign-on/ id/ ​

Permissions ​

Request ​

Response ​

Errors ​

DELETE /api/single-sign-on/id/ ​

Permissions ​

Request ​

Response ​

OPTIONS /api/single-sign-on/ ​

Permissions ​

Request ​

Response ​

POST /api/single-sign-on/login/ ​

Permissions ​

Request ​

Response ​

Errors ​

POST /api/single-sign-on/callback/id/ ​

Permissions ​

Request ​

Response ​

Errors ​

Single Sign On Configuration

Permissions

References

POST /api/single-sign-on/

Permissions

Request

Validations

Response

Errors

GET /api/single-sign-on/

Permissions

Request

Response

Response `results` array

Sorting

Filtering

Errors

GET /api/single-sign-on/ `id`/

Permissions

Request

Response

Errors

PATCH /api/single-sign-on/ `id`/

Permissions

Request

Response

Errors

DELETE /api/single-sign-on/`id`/

Permissions

Request

Response

OPTIONS /api/single-sign-on/

Permissions

Request

Response

POST /api/single-sign-on/login/

Permissions

Request

Response

Errors

POST /api/single-sign-on/callback/`id`/

Permissions

Request

Response

Errors