OAuth2.0

 

Login using OAuth2.0 is available since MediaHaven version 18.4. It is the preferred way of authenticating for new integrations.

1. Register your integration

First you must register your integration by creating a ticket on https://support.zeticon.com, or by emailing support@zeticon.com.

Your request must include the following information:

  • Company name / publisher

  • Name of your integration

  • Description of your integration

  • Destination server(s)

  • Redirect-URL(s)

If providing multiple redirect-uri(s), you will need to provide the correct one when making requests to the authentication portal

After we review your application, you will be sent a client_id and a client_secret which you can then use in the OAuth2.0 flow.

For this setup guide assume the following data. Swap out the data in the examples for your own values.

1 2 3 4 5 6 { "name": "Mediahaven OAuth2.0 Demo", "redirect_uri": "https://demo-app.com/redirect", "client_id": "882rgLgNTSqwBSnUUbC3qRiUfMGhorzZ", "client_secret": "KwfoaaXUDc6xdQKxBwxvxK55D4wZQ757", }

 

2. Obtaining a token

Client Credentials Grant a.k.a. interactive flow.

If your app offers a UI, you are required to use this flow

Redirect user to the MediaHaven Authentication Portal

Let's assume we want to connect to https://integration.mediahaven.com. For your actual connections, change the URL accordingly.

Kick-off the authorization flow by redirecting the user/browser to

https://integration.mediahaven.com/auth?client_id=882rgLgNTSqwBSnUUbC3qRiUfMGhorzZ

The user will be greeted by a MediaHaven login screen where he can login with one of the configured login options. Once logged in, the user will need to grant your app access to his account.

 

In 18.4 only default MediaHaven credentials are supported. Starting from version 19.1, if SAML login is configured, it will also be available here.

It is possible to automatically redirect to an external auth provider (as a means to set-up SSO) by using the autologin=<name-of-login-service> query parameter:
https://integration.mediahaven.com/auth?client_id=882rgLgNTSqwBSnUUbC3qRiUfMGhorzZ&autologin=mediahaven
Contact MediaHaven support if unsure on what value to use.

By default the authorization portal will auto-sense the language used by the end-user. Supported languages are nl, fr and en. It is possible to override this auto-sensing by adding the lang=<lang-code> query parameter:
https://integration.mediahaven.com/auth?client_id=882rgLgNTSqwBSnUUbC3qRiUfMGhorzZ&lang=nl

If the user clicks the "Authorize" option he will be redirected back to your initially registered Redirect-URL, with the Authorization code as query parameter:

https://demo-app.com/redirect?code=OORO1gjyWP7Mr9ztl2Dvp06NjR2kTApc

If you have multiple redirect_uri’s registered, you need to supply the correct one using the redirect_uri query parameter.

Redirect-URL are strictly matched. You can however add a state query parameter in your initial request to the auth portal, and it will be reflected when the user returns to your configured Redirect-URL

Swap Authorization code for an access token.

On your end, you would read the code query parameter from the URL and use it to obtain the access token.

The authorization_code can only be used once, and is only valid for a limited amount of time.

To obtain an actual access_token you would make a POST request to the following endpoint, and supply the code, client_id, client_secret and grant_type=authorization_code parameters

https://integration.mediahaven.com/auth/oauth2/token

Below is an example of the request with cURL. 

1 2 3 4 5 curl -X POST https://integration.mediahaven.com/auth/oauth2/token \ --data "grant_type=authorization_code" \ --data "code=OORO1gjyWP7Mr9ztl2Dvp06NjR2kTApc" \ --data "client_id=882rgLgNTSqwBSnUUbC3qRiUfMGhorzZ" \ --data "client_secret=KwfoaaXUDc6xdQKxBwxvxK55D4wZQ757"

If all goes well, you'll receive a  status 200 with the following JSON:

1 2 3 4 5 6 { "refresh_token":"1INOoUzpcFNa2diTVDGg86696mvJkUdZ", "token_type":"bearer", "access_token":"WySMF6lvPBsuV4X2tImsXe14zjzb1GEC", "expires_in":7200 }

It's also possible a statuscode != 200 is returned. You must take appropriate action.

Resource Owner Password Credentials

The Resource Owner Password Credentials grant is used when the application exchanges the user’s username and password for an access token.
This is something strongly advise not to use, but can be used.

 To obtain an access_token you would make a POST request to the following endpoint, and supply the code, client_idclient_secret , username and password parameters.

https://integration.mediahaven.com/auth/ropc.php

Below is an example of the request with cURL. 

1 2 3 4 5 curl -X POST https://integration.mediahaven.com/auth/ropc.php \     --data "username=username" \     --data "password=usernamespassword" \     --data "client_id=882rgLgNTSqwBSnUUbC3qRiUfMGhorzZ" \     --data "client_secret=KwfoaaXUDc6xdQKxBwxvxK55D4wZQ757"

 

If all goes well, you'll receive a  status 200 with the following JSON:

1 2 3 4 5 6 {     "refresh_token":"1INOoUzpcFNa2diTVDGg86696mvJkUdZ",     "token_type":"bearer",     "access_token":"WySMF6lvPBsuV4X2tImsXe14zjzb1GEC",     "expires_in":7200 }

It's also possible a statuscode != 200 is returned. You must take appropriate action.

3. Using the token

You can then use the access_token when making requests to the Rest-API by setting it in the Authorization header:

1 Authorization: bearer WySMF6lvPBsuV4X2tImsXe14zjzb1GEC
1 curl -X GET https://integration.mediahaven.com/mediahaven-rest-api/resources/media -H "Authorization: bearer WySMF6lvPBsuV4X2tImsXe14zjzb1GEC"

If you use the wrong token, or the token is expired, you will get a 401 response. You would then use the refresh token to obtain a new token.

4. Using the refresh token

The refresh token typically has an expiry date much further in the future. You can use this to obtain a new set of tokens.

You make a similar POST request as when requesting the token, but this time you supply the refresh_token and grant_type=refresh_token parameters.

1 2 3 4 5 curl -X POST https://integration.mediahaven.com/auth/oauth2/token \ --data "grant_type=refresh_token" \ --data "refresh_token=1INOoUzpcFNa2diTVDGg86696mvJkUdZ" \ --data "client_id=882rgLgNTSqwBSnUUbC3qRiUfMGhorzZ" \ --data "client_secret=KwfoaaXUDc6xdQKxBwxvxK55D4wZQ757"

 

If all goes well, you will get a 200 status code with a new access_token and refresh_token. The previous access_token and refresh_token will be invalid.

If the response returns a 401 Unauthorized, that means that the refresh_token has expired or your App permissions have been revoked. You would then start the flow back from the beginning.