{"_id":"59365227e16643001bac5050","category":{"_id":"59365227e16643001bac5034","version":"59365226e16643001bac5030","project":"543026235eceb608003fde5f","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-09-19T11:41:31.988Z","from_sync":false,"order":3,"slug":"test","title":"Advanced"},"project":"543026235eceb608003fde5f","user":"5736eb0b1a48812200566f0d","parentDoc":null,"version":{"_id":"59365226e16643001bac5030","project":"543026235eceb608003fde5f","__v":1,"createdAt":"2017-06-06T06:56:38.999Z","releaseDate":"2017-06-06T06:56:38.999Z","categories":["59365227e16643001bac5031","59365227e16643001bac5032","59365227e16643001bac5033","59365227e16643001bac5034"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0.0"},"__v":0,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-06-05T13:15:34.374Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":5,"body":"OAuth is an open standard for authorization. It provides protocols for client applications to obtain  permission to access a server resource on behalf of a user.\n\nGhost implements *OAuth 2.0 - Resource Owner Password Credentials Grant (RFC 6749, Section 4.3)* to allow a user to access a protected resource using username and password. The OAuth implementation essentially allows access tokens to be issued to the Ghost Admin, in exchange for valid user credentials. The Ghost Admin then uses the access token to access protected resources on the Ghost Server.\n\n**Please note: OAuth 2.0 is only secure if you use an encrypted connection (SSL/TSL)!**\n\n# Authentication flow\n\n\n```\n+----------+\n|          |\n|  User    |\n|          |\n+----------+\n     v\n     |     User\n    (1) Credentials\n     |\n     v\n+---------+                                  +------------+\n|         |>--(2)--------- User ------------>|            |\n|  Ghost  |             Credentials          |   Ghost    |\n|  Admin  |                                  |   Server   |\n|         |<--(3)------ Access Token -------<|            |\n+---------+                                  +------------+\n```\n(Source: RFC 6749)\n\n\n1) The user provides username and password\n2) Ghost Admin sends a post request to obtain an access token:\n\n```\nPOST /ghost/api/v0.1/authentication/token\n\nContent-Type: application/x-www-form-urlencoded\ngrant_type=password&username=<username>&password=<password>&client_id=ghost-admin\n```\n\n- `grant_type`: name of the authentication type\n- `username`: email address\n- `password`: secret password\n- `client_id`: name of the client that is requesting access on behalf of the user\n\n**Note**: The `username` parameter requires your email address, rather than your username.\n\n\n3) Ghost Server responds with access and refresh token\n\n```\n{\n   access_token: <access_token>\n   refresh_token: <refresh_token>\n   expires_in: 2628000\n   token_type: \"Bearer\"\n}\n```\n\n- `access_token`: users access token; valid for 1 month\n- `refresh_token`: users refresh token; valid for 6 months\n- `expires_in`: validity of the access_token in seconds\n- `token_type`: access token type\n\n# Usage\n\nTo access a resource on the server the access_token is sent as Authorization header.\n\n```\nGET /ghost/api/v0.1/users/me/\nAuthorization: Bearer <access_token>\n```\n\nThe access token is stored in local storage and synchronized with all open windows. Token management is done using `ember-simple-auth`, a lightweight library that handles tokens and adds the authorization header to every request that is sent from Ghost Admin. If an access token is about to expire the refresh token is used to get a new access token without asking the user for its authentication credentials.\n\n1) Ghost Admin sends a request to refresh an access token:\n\n```\nPOST /ghost/api/v0.1/authentication/token\n\nContent-Type: application/x-www-form-urlencoded\ngrant_type=refresh_token&refresh_token=<refresh_token>&client_id=ghost-admin\n```\n\n- `grant_type`: name of the authentication type\n- `refresh_token`: refresh token\n- `client_id`: name of the client that is requesting access on behalf of the user\n\n2) Ghost Server responds with a new access token\n\n```\n{\n    access_token: <access_token>\n    expires_in: 2628000\n    token_type: \"Bearer\"\n}\n```\n\n- `access_token`: users access token; valid for 1 month\n- `expires_in`: validity of the access_token in seconds\n- `token_type`: access token type\n\nThe refresh mechanism works as long as the refresh token is valid, after expiry the user has to sign in again.\n\n# Ghost Implementation\n\nGhost only supports a very small set of OAuth features at the moment. The implementation is extensible and further authentication methods are going to be implemented in future releases.\n\nUsed Libraries:\n- **oauth2orize** (https://github.com/jaredhanson/oauth2orize) is used for the backend implementation. It handles the generation of access tokens from the username and password using the  `oauth2orize.exchange.password` middleware and refreshing of an access tokens using the `oauth2orize.exchange.refreshToken` middleware.\n\n- **ember-simple-auth** (https://github.com/simplabs/ember-simple-auth) is used to implement the resource owner password credentials grant for the client.","excerpt":"","slug":"how-does-oauth-work-with-ghost","type":"basic","title":"How does OAuth work with Ghost?"}

How does OAuth work with Ghost?


OAuth is an open standard for authorization. It provides protocols for client applications to obtain permission to access a server resource on behalf of a user. Ghost implements *OAuth 2.0 - Resource Owner Password Credentials Grant (RFC 6749, Section 4.3)* to allow a user to access a protected resource using username and password. The OAuth implementation essentially allows access tokens to be issued to the Ghost Admin, in exchange for valid user credentials. The Ghost Admin then uses the access token to access protected resources on the Ghost Server. **Please note: OAuth 2.0 is only secure if you use an encrypted connection (SSL/TSL)!** # Authentication flow ``` +----------+ | | | User | | | +----------+ v | User (1) Credentials | v +---------+ +------------+ | |>--(2)--------- User ------------>| | | Ghost | Credentials | Ghost | | Admin | | Server | | |<--(3)------ Access Token -------<| | +---------+ +------------+ ``` (Source: RFC 6749) 1) The user provides username and password 2) Ghost Admin sends a post request to obtain an access token: ``` POST /ghost/api/v0.1/authentication/token Content-Type: application/x-www-form-urlencoded grant_type=password&username=<username>&password=<password>&client_id=ghost-admin ``` - `grant_type`: name of the authentication type - `username`: email address - `password`: secret password - `client_id`: name of the client that is requesting access on behalf of the user **Note**: The `username` parameter requires your email address, rather than your username. 3) Ghost Server responds with access and refresh token ``` { access_token: <access_token> refresh_token: <refresh_token> expires_in: 2628000 token_type: "Bearer" } ``` - `access_token`: users access token; valid for 1 month - `refresh_token`: users refresh token; valid for 6 months - `expires_in`: validity of the access_token in seconds - `token_type`: access token type # Usage To access a resource on the server the access_token is sent as Authorization header. ``` GET /ghost/api/v0.1/users/me/ Authorization: Bearer <access_token> ``` The access token is stored in local storage and synchronized with all open windows. Token management is done using `ember-simple-auth`, a lightweight library that handles tokens and adds the authorization header to every request that is sent from Ghost Admin. If an access token is about to expire the refresh token is used to get a new access token without asking the user for its authentication credentials. 1) Ghost Admin sends a request to refresh an access token: ``` POST /ghost/api/v0.1/authentication/token Content-Type: application/x-www-form-urlencoded grant_type=refresh_token&refresh_token=<refresh_token>&client_id=ghost-admin ``` - `grant_type`: name of the authentication type - `refresh_token`: refresh token - `client_id`: name of the client that is requesting access on behalf of the user 2) Ghost Server responds with a new access token ``` { access_token: <access_token> expires_in: 2628000 token_type: "Bearer" } ``` - `access_token`: users access token; valid for 1 month - `expires_in`: validity of the access_token in seconds - `token_type`: access token type The refresh mechanism works as long as the refresh token is valid, after expiry the user has to sign in again. # Ghost Implementation Ghost only supports a very small set of OAuth features at the moment. The implementation is extensible and further authentication methods are going to be implemented in future releases. Used Libraries: - **oauth2orize** (https://github.com/jaredhanson/oauth2orize) is used for the backend implementation. It handles the generation of access tokens from the username and password using the `oauth2orize.exchange.password` middleware and refreshing of an access tokens using the `oauth2orize.exchange.refreshToken` middleware. - **ember-simple-auth** (https://github.com/simplabs/ember-simple-auth) is used to implement the resource owner password credentials grant for the client.