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

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

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

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

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

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

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

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