Identity providers
Identity providers (IDPs) are used in conjunction with Single Sign-On (SSO) SAML2 to authenticate users. As such, you will need to make sure SSO is included in your account/package to make use of identity providers.
Often you will only have one identity provider. However for larger organisations you may authenticate your employees using alternative systems. You can manage your identity providers by making the following requests:
GET /idps
Example request
curl \
-H "Authorization: Bearer YOUR-API-KEY" \
"https://api.vidbeo.com/v2/idps"
Example response
{
"success": true,
"result": [
{
"id": "abcde12345abcde12345a",
"name": "Example idp",
"company": "other",
"type": "saml2",
"certificate": "MII...",
"entity_id": "https://example.com",
"signin_url": "https://example.com",
"digest_algorithm": "sha256",
"signature_algorithm": "sha256",
"created_by": "abcde12345abcde1234a",
"created_time": "2022-01-01T00:00:00.000Z",
"updated_by": "abcde12345abcde12345a",
"updated_time": "2022-01-01T00:00:00.000Z"
},
...
],
"links": {},
"errors": []
}
Optional parameters
| Name | Type | Default | Information |
|---|---|---|---|
| limit | String | 25 | Maximum number to return |
| cursor | String | "" | Used to get the next page of results: if applicable we return this as part of the links.next URL |
GET /idps/:id
Example request
curl \
-H "Authorization: Bearer YOUR-API-KEY" \
"https://api.vidbeo.com/v2/idps/abcde12345abcde12345a"
Example response
{
"success": true,
"result": {
"id": "abcde12345abcde12345a",
"name": "Example idp",
"company": "other",
"type": "saml2",
"certificate": "MII...",
"entity_id": "https://example.com",
"signin_url": "https://example.com",
"digest_algorithm": "sha256",
"signature_algorithm": "sha256",
"created_by": "abcde12345abcde1234a",
"created_time": "2022-01-01T00:00:00.000Z",
"updated_by": "abcde12345abcde12345a",
"updated_time": "2022-01-01T00:00:00.000Z"
},
"links": null,
"errors": []
}
Response format
| Key | Type | Description |
|---|---|---|
| id | String | The unique identifier given to this idp |
| name | String | The name given to this idp |
| company | String | The company name, used to assign a logo/icon in the UI. May be 'other' |
| type | String | Currently only 'saml2' IDPs are supported |
| certificate | String | The public certificate the IDP will provide |
| entity_id | String | The entity ID your application uses |
| signin_url | String | The URL the IDP expects SAML2 requests to be POSTed to |
| digest_algorithm | String | Currently only the standard 'sha256' is supported |
| signature_algorithm | String | Currently only the standard 'sha256' is supported |
| created_by | String | The ID of the user who created it (if known) |
| created_time | String | The date and time it was created |
| updated_by | String | The ID of the user who last modified it (if known) |
| updated_time | String | The date and time it was last modified |
PATCH /idps/:id
The body of the request should contain one, or more, attributes that you would like to update for the idp. Please be careful when making changes to existing items to avoid losing data, particularly if a particular key has sub-keys.
Example request
curl \
-g \
-H "Authorization: Bearer YOUR-API-KEY" \
-H "Content-Type: application/json" \
-X PATCH \
-d '{"name":"New name"}' \
"https://api.vidbeo.com/v2/idps/abcde12345abcde12345a"
Example response
{
"success": true,
"result": {
"id": "abcde12345abcde12345a",
"name": "New name",
"company": "other",
"type": "saml2",
"certificate": "MII...",
"entity_id": "https://example.com",
"signin_url": "https://example.com",
"digest_algorithm": "sha256",
"signature_algorithm": "sha256",
"created_by": "abcde12345abcde1234a",
"created_time": "2022-01-01T00:00:00.000Z",
"updated_by": "abcde12345abcde12345a",
"updated_time": "2022-01-01T00:00:00.000Z"
},
"links": null,
"errors": []
}
DELETE /idps/:id
Example request
curl \
-H "Authorization: Bearer YOUR-API-KEY" \
-X DELETE \
"https://api.vidbeo.com/v2/idps/abcde12345abcde12345a"
Example response
{
"success": true,
"result": {},
"links": null,
"errors": []
}
POST /idps
Example request
curl \
-g \
-H "Authorization: Bearer YOUR-API-KEY" \
-H "Content-Type: application/json" \
-X POST \
-d '{"name":"Google", "company":"google", "type":"saml2"}' \
"https://api.vidbeo.com/v2/idps"
Example response
{
"success": true,
"result": {
"id": "abcde12345abcde12345a",
"name": "Google",
"company": "google",
"type": "saml2",
"certificate": "",
"entity_id": "",
"signin_url": "",
"digest_algorithm": "sha256",
"signature_algorithm": "sha256",
"created_by": "abcde12345abcde1234a",
"created_time": "2022-01-01T00:00:00.000Z",
"updated_by": "abcde12345abcde12345a",
"updated_time": "2022-01-01T00:00:00.000Z"
},
"links": null,
"errors": []
}
Required parameters
The required parameters: a name for the identity provider, a value for company to show a logo/icon (if not sure, use 'other'), and a type of 'saml2' (the only supported type for now).
| Key | Type | Description |
|---|---|---|
| name | String | The name of the idp (1-100 characters) |
| company | String | A lowercase string to show a logo by its name in the UI |
| type | String | Currently only 'saml2' is supported for the IDP's type |
Optional parameters
| Key | Type | Description |
|---|---|---|
| certificate | String | The public certificate the IDP will provide |
| entity_id | String | The entity ID your application uses |
| signin_url | String | The URL the IDP expects SAML2 requests to be POSTed to |
Creating the IDP will add it to the database. However for it to be usable you will still need to provide the three optional parameters via a subsequent PATCH /idps/:id if not initially provided. Since our system needs the signin_url to know where to send (POST) SSO requests from your users, and we need the entity_id and certificate to verify SSO responses from your IDP. You should be able to get all those values from your IDP.