Platform authorization

Access Token

The client needs to obtain access token before calling services. Token is generated as a part of successful login. Before doing the login, the client must select identity provider as an authority that handles the login / verifies user credentials. Potentially, there are many identity providers, so the client must fetch the list of available providers, "select" one of them, do the login against a chosen provider in a provider-specific way. This overall process is driven by hypermedia. Authentication is described by media type based on Hypertext Application Language (HAL)

For an accessing list of available providers, a client should call to /auth resource by issuing following request

Request GET https://[host]/auth

Headers

  • "Content-Type":"application/json"
  • "Accept":"application/json"

Response 200 OK

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
{
"_links":{
"curies":[
{
"href":"https://[host]/auth/def/rels/{rel}",
"name":"auth",
"templated":true
}
],
"self":{
"href":"https://[host]/auth"
},
"auth:identity-providers":[
{
"href":"https://[host]/auth/identity-providers"
}
],
"auth:logout":[
{
"href":"https://[host]/auth/logout/reactive",
"name":"reactive"
}
],
"auth:sso-login":[
{
"href":"https://[host]/auth/sso/login/start/auto",
"name":"start-auto"
},
{
"href":"https://[host]/auth/sso/login/start/auto{?IdpAdapterId}",
"name":"start-auto-tpl",
"templated":true
},
{
"href":"https://[host]/auth/sso/login/saml2",
"name":"SAML2"
}
],
"auth:token":[
{
"href":"https://[host]/auth/tokens/current",
"name":"current"
}
]
}
}

Link with relationship auth:identity-providers points to a list of available identity-providers. A client should fetch a list by issuing following request

Request GET https://[host]/auth/identity-providers

Headers

  • "Content-Type":"application/json"
  • "Accept":"application/json"

Response 200 OK

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
{
"_links":{
"curies":[
{
"href":"https://[host]/auth/def/rels/{rel}",
"name":"auth",
"templated":true
},
{
"href":"https://[host]/auth/identity-providers/kind/mcux/def/rels/{rel}",
"name":"auth-mcux",
"templated":true
},
{
"href":"https://[host]/auth/identity-providers/kind/ping-federate/def/rels/{rel}",
"name":"auth-ping-federate",
"templated":true
}
],
"self":{
"href":"https://[host]/auth/identity-providers"
}
},
"_embedded":{
"auth:identity-provider":[
{
"_links":{
"auth-ping-federate:idp-sso":[
{
"href":"https://ssotst.avid.com/idp/startSSO.ping?PartnerSpId=ae.avid.com&IdpAdapterId=avidMasterSSOIDP2&ACSIdx=75{&TargetResource,InErrorResource,Binding,RequestedFormat}",
"templated":true
}
]
},
"kind":"ping-federate"
},
{
"_links":{
"auth-mcux:login":[
{
"href":"https://[host]/api/auth/login"
}
]
},
"kind":"mcux"
}
]
}
}

The embedded resources contain list of all available identity providers including the link for immediate authorization procedures and identity provider kind. Depends on selected identity provider authorization flow may defer however success authorization always ends with retrieving avidAccessToken and user IAM token.

IAM token is a platform internal user identifier. Its lifecycle closely related to access token so IAM expiration date could be threaded as access token expiration date (see Verifying, extending and revoking access token section).

Access token should be specified in each request against platform resources. There are three ways to pass access token in request:

  • as cookies
  • as authorization header. For example, Authorization: Bearer NTc4Y2U3MWMtMjdhMS00ZGZhLThjZWQtODViZmFmODU1YTgw
  • as query parameter. For example, https://[host]/auth/tokens/current?_avidAccessToken=NTc4Y2U3MWMtMjdhMS00ZGZhLThjZWQtODViZmFmODU1YTgw

Please note that some platform services may use their own authorization approach, so having valid access token may be not enough. As for example, accessing media central resources will require valid session (JSESSION cookie). This is a legacy limitation which will be removed in future

MCUX identity provider

MCUX identity provider allows to pass platform authorization based on existing MCUX user credentials. In order to pass authorization, a client should issue request against a link specified in auth-mcux:login embedded resource of identity-providers resource as following.

Request POST https://[host]/api/auth/login

Headers

  • "Content-Type":"application/json"
  • "Accept":"application/json"
1
2
3
4
{
"username":"UserName",
"password":"Password"
}

Response 303 See Other

Headers

  • Set-Cookie: JSESSION=00912aaSsdasdAShMS00ZGZhLThjZWQtODViZmFmODU1YTgw;
  • Set-Cookie: avidAccessToken=NTc4Y2U3MWMtMjdhMS00ZGZhLThjZWQtODViZmFmODU1YTgw;
  • Location: https://[host]/auth/tokens/current

Response [after redirection] 200 Ok

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
{
"_links":{
"curies":[
{
"href":"https://[host]/auth/def/rels/{rel}",
"name":"auth",
"templated":true
},
{
"href":"https://[host]/auth/tokens/rels/{rel}",
"name":"auth-token",
"templated":true
}
],
"self":{
"href":"https://[host]/auth/tokens/current"
},
"auth-token:extend":[
{
"href":"https://[host]/auth/tokens/current/extension"
}
],
"auth-token:removal":[
{
"href":"https://[host]/auth/tokens/current"
}
]
},
"accessToken":"NTc4Y2U3MWMtMjdhMS00ZGZhLThjZWQtODViZmFmODU1YTgw",
"iamToken":{
"identityId":"d3e652e3-2c02-4ff3-bf70-c68a318bc6fc",
"identityMasterRegion":"default-region",
"contextId":"d3e652e3-2c02-4ff3-bf70-c68a318bc6fc",
"contextMasterRegion":"default-region",
"expiresAt":"2016-06-21T10:04:33.477Z",
"createdAt":"2016-06-21T09:49:33.477Z",
"updatedAt":"2016-06-21T09:49:33.477Z",
"masterRegion":"default-region",
"id":"578ce71c-27a1-4dfa-8ced-85bfaf855a80"
}
}

After successful login client will get valid access token as well as valid session (JSESSION cookie, required for accessing media central resources. Please note that revoking and extending access token will be applied to media central session as well).

Verifying, extending and revoking access token

Avid access token has an expiration date defined by IAM token expiration date. A client could always get expiration date by issuing auth:token link with name current supplied in /auth response.

For example issuing following request with valid access token will result complete information about iamToken (which access token is bind to) including creation, last updated and expiration date (as an string representing ISO-860-1 date format).

Request GET https://[host]/auth/tokens/current?_avidAccessToken=NTc4Y2U3MWMtMjdhMS00ZGZhLThjZWQtODViZmFmODU1YTgw

Headers

  • "Content-Type":"application/json"
  • "Accept":"application/json"

Response 200 OK

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
{
"_links":{
"curies":[
{
"href":"https://[host]/auth/def/rels/{rel}",
"name":"auth",
"templated":true
},
{
"href":"https://[host]/auth/tokens/rels/{rel}",
"name":"auth-token",
"templated":true
}
],
"self":{
"href":"https://[host]/auth/tokens/current"
},
"auth-token:extend":[
{
"href":"https://[host]/auth/tokens/current/extension"
}
],
"auth-token:removal":[
{
"href":"https://[host]/auth/tokens/current"
}
]
},
"accessToken":"OTQwMDFkNWItM2ViYy00ZmZmLTg2OGEtODc3YzA4MGRhMWFm",
"iamToken":{
"identityId":"d3e652e3-2c02-4ff3-bf70-c68a318bc6fc",
"identityMasterRegion":"default-region",
"contextId":"d3e652e3-2c02-4ff3-bf70-c68a318bc6fc",
"contextMasterRegion":"default-region",
"expiresAt":"2016-06-21T10:46:22.683Z",
"createdAt":"2016-06-21T10:31:22.683Z",
"updatedAt":"2016-06-21T10:31:22.683Z",
"masterRegion":"default-region",
"id":"94001d5b-3ebc-4fff-868a-877c080da1af"
}
}

Current token resource provides also links for token extending and revoking.

Token verification

Same as above, current token resource could be used for token verification. So in case request to current token will result 401 Unauthorized response, then token is not a valid (aka expired or revoked)

Request GET https://[host]/auth/tokens/current?_avidAccessToken=NTc4Y2U3MWMtMjdhMS00ZGZhLThjZWQtODViZmFmODU1YTgw

Headers

  • "Content-Type":"application/json"
  • "Accept":"application/json"

Response 401 Unauthorized

1
2
3
4
5
6
7
{
"code":"avid.upstream/UNAUTHENTICATED",
"message":"Access token is invalid",
"incident":"e7be3641-379b-11e6-ae61-06a2180005e8",
"exchange":"e7be3640-379b-11e6-ae61-06a2180005e8",
"status":401
}

In case token become invalid, there is no way to refresh token except of pass authorization again.

Token extending

Current token resource contains link for extending token (auth-token:extend) Issuing request as following will extend token.

Exact extending value depends on a platform configuration and could not be supplied in request.

Request POST https://[host]/auth/tokens/current/extension?_avidAccessToken=NTc4Y2U3MWMtMjdhMS00ZGZhLThjZWQtODViZmFmODU1YTgw

Headers

  • "Content-Type":"application/json"
  • "Accept":"application/json"

Response 200 OK

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
{
"_links":{
"curies":[
{
"href":"https://[host]/auth/def/rels/{rel}",
"name":"auth",
"templated":true
},
{
"href":"https://[host]/auth/tokens/rels/{rel}",
"name":"auth-token",
"templated":true
}
],
"self":{
"href":"https://[host]/auth/tokens/current/extension"
},
"auth:token":[
{
"href":"https://[host]/auth/tokens/current"
}
]
},
"accessToken":"QQQQASKJASNCSIWQHEajhsdkLTk3ZWMtMjI1MjNhMDMwODg4",
"iamToken":{
"identityId":"d3e652e3-2c02-4ff3-bf70-c68a318bc6fc",
"identityMasterRegion":"default-region",
"contextId":"d3e652e3-2c02-4ff3-bf70-c68a318bc6fc",
"contextMasterRegion":"default-region",
"expiresAt":"2016-06-21T10:59:47.467Z",
"createdAt":"2016-06-21T10:49:47.046Z",
"updatedAt":"2016-06-21T10:49:47.467Z",
"masterRegion":"default-region",
"expired":false,
"id":"9e90d6d5-21d0-449f-97ec-22523a030888"
}
}

Where iamToken.expiresAt will contains new expiration date as a ISO-860-1 date format.

A client MUST refresh / replace the token on it's side since access token MAY be rotated by the server.

Token revoking

Current token resource contains link for revoking token (auth-token:removal) Issuing request as following will revoke a token

Request DELETE https://[host]/auth/tokens/current?_avidAccessToken=NTc4Y2U3MWMtMjdhMS00ZGZhLThjZWQtODViZmFmODU1YTgw

Headers

  • "Content-Type":"application/json"
  • "Accept":"application/json"

Response 204 No Content

After this token will be treated by platform as invalid so a client will be not able to access any of platform resource using this particular access token.

Please note that some resources will be still available for some period of time depend on how long synchronization process will take. For example, MC resources will be available for more 1-2 minutes