# oAuth2 authorization

This guide walks you through using oAuth 2 authorization for SDKs that require it. For oAuth 2 tutorial see [An Introduction to OAuth 2](https://www.digitalocean.com/community/tutorials/an-introduction-to-oauth-2).

## Step by step guide

### 1. Provide your information

At first step you need to provide your information issued by the CSAS. This includes `clientId`, `clientSecret` and `redirectUri`. `clientId` is always required while `clientSecret` and `redirectUri` are optional. For reference see [`Oauth2Config`](../lib/core/web-api-configuration.ts#47). Provide this information to the `CoreSDK` by calling its `useOauth2` method and pass it config `object` with the mentioned information. See [`useOauth2`](../lib/core-sdk.ts#57) definition.

```js

  CSCoreSDK.useOauth2({
    clientId: 'your client id',
    redirectUri: 'your redirect uri'
  });

```

### 2a. Get authorization url

Now you can get authorization url. Get the authorization url by calling the `getOauth2Url` method on CoreSDK's `sharedContext` property. The `getOauth2Url` methods returns url in `string` to CSAS login page. See [`getOauth2Url`](../lib/core/oauth-provider.ts#14) definition.

```js

  var url = CSCoreSDK.sharedContext.getOauth2Url();

```

### 3a. Process callback redirect URL

When user is redirected back to your app to redirect uri you specified you can use [`processRedirect`](../lib/core/oath-provider#22) method to extract and use information provided by the CSAS like `code` if you use code flow or `token`, `token_type` and `expires_in` if you use implicit flow. Then it sets the `accessToken` or `code`  to [`AccessTokenProvider`](../lib/core/access-token-provider.ts#8) for further calls and refreshing token if you use code flow and it also returns the `token`.

```js

  var url = 'http://somesite.com/some/path#/access_token=ASDPOWQI80808ADASD&expires_in=3600&token_type=bearer&lang=cs'

  CSCoreSDK.sharedContext.processRedirect(url)
    .then(token => {

    });

```

### 2b. Set access token

If you already have access token you can use [`useAccessToken`](../lib/core/web-api-context.ts#46) method on set it directly to the [`AccessTokenProvider`](../lib/core/access-token-provider.ts#8). The `useAccessToken` method takes either [`AccessToken`](../lib/core/access-token-provider.ts#179) object with `token`, `tokenType` and `expiresIn` or `token` as a string.

```js

  // provided full AccessToken
  CSCoreSDK.sharedContext.useAccessToken({
    token: 'some token',
    tokenType: 'bearer',
    expiresIn: 1489049819536,
  });

  // or token as string

  CSCoreSDK.sharedContext.useAccessToken('some token');

```

### 2c. Set code

If you are using code flow and already have `code` you can use [`useCode`](../lib/core/web-api-context.ts#53) to set it directly to the [`AccessTokenProvider`](../lib/core/access-token-provider.ts#8).

```js

  CSCoreSDK.sharedContext.useCode('some code');

```

## sharedContext API reference

### getAccessToken

If you have have already went through the authorization you can use [`getAccessToken`](../lib/core/web-api-context.ts#15) to get `accessToken`. It returns the `accessToken` in `Promise` if `accessToken` is not expired or tries to refresh the token if it is expired but code flow is used.

```js
  
  CSCoreSDK.sharedContext.getAccessToken()
    .then(accessToken => {

    }, error => {

    });

```

### refreshAccessToken

You can use [`refreshAccessToken`](../lib/core/web-api-context.ts#24) to refresh `accessToken` directly if you are using code flow. Please note that the SDK refreshes the `accessToken` automatically if you are using code flow and `accessToken` is expired.

```js
  
  CSCoreSDK.sharedContext.refreshAccessToken()
    .then(accessToken => {

    }, error => {

    });

```

### getOauth2Url

[`getOauth2Url`](../lib/core/web-api-context.ts#32) returns URL where user should authenticate.

```js

  var oauthUrl = CSCoreSDK.sharedContext.getOauth2Url();

```

### processRedirect

[`processRedirect`](../lib/core/oath-provider#22) extracts and uses information provided by the CSAS like `code` if you use code flow or `token`, `token_type` and `expires_in` if you use implicit flow. Then it sets the `accessToken` or `code`  to [`AccessTokenProvider`](../lib/core/access-token-provider.ts#8) for further calls and refreshing token if you use code flow and it also returns the `token`.

```js

  var url = 'http://somesite.com/some/path#/access_token=ASDPOWQI80808ADASD&expires_in=3600&token_type=bearer&lang=cs'

  CSCoreSDK.sharedContext.processRedirect(url)
    .then(token => {

    });

```

### useAccessToken

[`useAccessToken`](../lib/core/web-api-context.ts#46) method sets `accessToken` directly to the [`AccessTokenProvider`](../lib/core/access-token-provider.ts#8). The method takes either [`AccessToken`](../lib/core/access-token-provider.ts#179) object with `token`, `tokenType` and `expiresIn` or `token` as a string.

```js

  // provided full AccessToken
  CSCoreSDK.sharedContext.useAccessToken({
    token: 'some token',
    tokenType: 'bearer',
    expiresIn: 1489049819536,
  });

  // or token as string

  CSCoreSDK.sharedContext.useAccessToken('some token');

```

### useCode

[`useCode`](../lib/core/web-api-context.ts#53) takes `code` as string as a first parameter and sets it directly to the [`AccessTokenProvider`](../lib/core/access-token-provider.ts#8).

```js

  CSCoreSDK.sharedContext.useCode('some code');

```

### getCode

[`getCode`](../lib/core/web-api-context.ts#60) returns `code` used for authentication.

```js

  var code = CSCoreSDK.sharedContext.getCode();

```