Skip to content

Commit

Permalink
Incorporate editorial feedback
Browse files Browse the repository at this point in the history
  • Loading branch information
@carolynvs
carolynvs committed Apr 7, 2016
1 parent 01cadec commit 3988c9d
Show file tree
Hide file tree
Showing 2 changed files with 61 additions and 52 deletions.
Binary file modified _assets/img/oauth-integration/developer-apps.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
113 changes: 61 additions & 52 deletions _reference/2016-04-08-oauth-integration.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
title: OAuth Integration
title: OAuth integration
author: Carolyn Van Slyck <[email protected]>
date: 2016-04-08
permalink: docs/reference/oauth-integration/
Expand All @@ -8,32 +8,34 @@ description: Learn how to integrate your application with Carina using OAuth

Carina supports OAuth v2 for integration with external applications.
OAuth is an authentication protocol that allows users to grant limited access
to their account without sharing their password. With Carina OAuth you can
authenticate a user, download their cluster credentials or create a cluster on
to their account without sharing their password. With Carina OAuth, you can
authenticate users, download their cluster credentials, and create clusters on
their behalf.

* [OAuth Dance](#oauth-dance)
* [OAuth dance](#oauth-dance)
* [Register your application](#register-your-application)
* [Configure your application](#configure-your-application)
* [Interact with Carina](#interact-with-carina)

## OAuth Dance
### OAuth dance
The flow that a user experiences when authorizing an application
is sometimes called the "OAuth dance", due to the back and forth communication between
the external application and OAuth provider.
is sometimes called the "OAuth dance" because of the back-and-forth communication between
the external application and OAuth provider. The following process describes
that dance with Carina.

1. The external application requests permission to access the user's Carina account.
Usually this will be a log in or authorize button on their website.
Usually this request happens when a user clicks a login or authorize button
on the application's website.

![OAuth prompt]({% asset_path oauth-integration/signin-prompt.png %})

1. The user is redirected to the Carina OAuth website where, if the user is not logged in,
they are prompted for their Rackspace credentials. These are used to authenticate
the user against Carina, and are not shared with the external application.
1. The user is redirected to the Carina OAuth website. If the user is not logged in,
the user is prompted for Rackspace credentials. These credentials are used to authenticate
the user against Carina and are not shared with the external application.

![Carina OAuth log in form]({% asset_path oauth-integration/oauth-signin.png %})

1. The user is presented with an authorization form, listing the permissions
1. The user is presented with an authorization form that lists the permissions
requested by the application.

![Carina OAuth Request]({% asset_path oauth-integration/authorize-app.png %})
Expand All @@ -46,35 +48,39 @@ and revoke an application's access.

![Manage Authorized Applications]({% asset_path oauth-integration/authorized-apps.png %})

## Register your application
Before you can integrate with Carina, you must first register your application.
### Register your application
Before your application can integrate with Carina, you must first register the application.

1. Log in to the [Carina OAuth][carina-oauth] website.

1. Click the **Developer Applications** link and log in with your Carina credentials.

1. On the Developer Applications page, click **New Application**.

![Manage Developer Applications]({% asset_path oauth-integration/developer-apps.png %})

1. Complete the registration form. The **Redirect URI** specifies the URL to which
the user is directed after they authorize your application. It must be a secure
webpage, starting with `https`.
users are directed after they authorize your application. It must be a secure
web page, starting with `https`.

![Register Developer Application]({% asset_path oauth-integration/register-app.png %})

1. On the confirmation page, your **Application Id** and **Secret** are displayed.
The secret must not be shared publicly and should not be checked into source control.
On the confirmation page, the application ID and secret are displayed. Do not share
the secret publicly, and do not check it in to source control.

![Register Developer Application]({% asset_path oauth-integration/app-secrets.png %})
![Register Developer Application]({% asset_path oauth-integration/app-secrets.png %})

## Configure your application
### Configure your application
Select an [OAuth2 library][oauth-libs] for the programming language used by your application.
Depending on the library, some or all of the following configuration is handled
by the library. The following guidelines are generic, see the documentation
by the library. The following guidelines are generic; see the documentation
for your particular library for additional details.

1. In your application, configure the library to use your **Application Id**, **Secret** and **Callback URL**.
1. In your application, configure the library to use the application ID, secret
and redirect URI for your registered application in the Carina OAuth
Control Panel.

1. Add a link to your application which requests access to the user's Carina account.
1. Add a link to your application that requests access to the user's Carina account.
Replace `<applicationId>`, and `<redirectURI>` with the values from your application
registration.

Expand All @@ -86,16 +92,17 @@ for your particular library for additional details.
`&scope=identity+cluster_credentials+create_cluster`

1. Add a webpage to your application that handles requests to your Redirect URI.
After the user authorizes your application, the user is redirected to this webpage

After the user authorizes your application, the user is redirected to this page
with the authorization `code` included in the query string.

`https://example.com/carina-oauth-callback?code=abc123`

1. The callback webpage should use the authorization code to request a token,
and then store the returned tokens. The `access_token` has an expiration date,
after which the `refresh_token` can be used to request a new token.
The callback web page should use the authorization code to request a token,
and then store the returned tokens. The `access_token` value has an expiration date,
after which the `refresh_token` value can be used to request a new token.

**Example Request**
**Example request**

`POST https://oauth.getcarina.com/oauth/token`

Expand All @@ -109,7 +116,7 @@ for your particular library for additional details.
}
```

**Example Response**
**Example response**

```json
{
Expand All @@ -121,52 +128,52 @@ for your particular library for additional details.
```


## Interact with Carina
### Interact with Carina
The following OAuth scopes are available, granting your application varying
levels of access to a user's account.

* [Identity](#identity-scope)
* [Cluster Credentials](#cluster-credentials-scope)
* [Create Cluster](#create-cluster-scope)
* [Identity](#identity)
* [Cluster credentials](#cluster-credentials)
* [Create cluster](#create-cluster)

All requests must include an authorization header, `Authorization: bearer <access_token>`,
replacing `<access_token>`, with the OAuth token returned from the `/oauth/token` endpoint.
replacing `<access_token>` with the OAuth token returned from the `/oauth/token` endpoint.

### Identity Scope
The `identity` scope enables an application to read a user's profile. Due to the
limited amount of information in a users' profile, this is mainly useful for delegating your
application's authentication to Carina.
#### Identity
The `identity` scope enables an application to read a user's profile. Because the
amount of information in a user's profile is limited, this scope is mainly useful
for delegating your application's authentication to Carina.

**Example Request**
**Example request**

`GET https://oauth.getcarina.com/me`

**Example Response**
**Example response**

```json
{
"id": 1,
"username": "carolynvs",
"email": "[email protected]",
"email": "carolynvs",
"full_name": "carolynvs"
}
```

### Cluster Credentials Scope
#### Cluster credentials
The `cluster_credentials` scope enables an application to download the credentials
zip file for a users's Carina cluster. Replace `<clusterName>` with name of the cluster.
zip file for a user's Carina cluster. Replace `<clusterName>` with name of the cluster.

**Example Request**
**Example request**

`GET https://oauth.getcarina.com/clusters/<clusterName>`

**Example Responses**
**Example responses**

The body of the response is the user's cluster credentials zip file, provided as
an `application/zip` encoded binary attachment.

If the cluster is not yet active, a `404 NOT FOUND` response is returned.
After creating a new cluster, it can take 2-3 minutes for the cluster to become active.
After a new cluster is created, it can take 2-3 minutes for the cluster to become active.
Poll the cluster credentials endpoint at a reasonable interval, such as every 30 seconds,
until the cluster is active.

Expand All @@ -176,16 +183,18 @@ until the cluster is active.
}
```

### Create Cluster Scope
The `create_cluster` scope enables an application to create a cluster on the users'
Carina account. If the cluster already exists, the request succeeds and the cluster
information is returned. Replace `<clusterName>` with the name of the cluster to create.
#### Create cluster
The `create_cluster` scope enables an application to create a cluster on the user's
Carina account. Replace `<clusterName>` with the name of the cluster to create.

**Note**: If the cluster already exists, rather than returning an error, the request
is considered successful and the cluster information is returned.

**Example Request**
**Example request**

`PUT https://oauth.getcarina.com/clusters/<clusterName>`

**Example Response**
**Example response**

```json
{
Expand Down

0 comments on commit 3988c9d

Please sign in to comment.