OAuth 2¶
General information¶
Before OAuth2 authentication with pCon.login can be used a client has to be registered. To request registration of a new client please send an email with the following information to support@easterngraphics.com:
- cliend_id:
Client id of the application, must be unique and should be limited to [a-z-A-Z0-9_-]
- name:
A descriptive name for the application
- redirect_uris:
URIs that are acceptable as return URL for this application More information on this is available in the description of the separate flows. Currently all registered URLs will also permit all subpaths. e.g: https://example.com/foo/oauth will permit all of the following urls:
- default_redirect_uri:
Default redirect uri to use
- required_scopes:
Scopes that are required by the application (See Scopes and documentation of the APIs you want to use)
- intended_flows:
OAuth supports serveral diffent flows depending on the use case of the application. The flows supported by pCon.login are further described in this document.
- supports_long_term_tokens:
Whether to support long term service tokens. (this also implies that the refresh token flow will be enabled for this client) Usually this is not needed.
- pcon_session:
Whether the client is considered part of the common “pcon” session. This mainly effects logout behaviour: When the user logs out all tokens belonging to “pcon” clients will be expired.
- contact_email:
Email address of a person/group responsible for that client. We recommend a function-related email address (e.g. example-product-manager@company.com) to ensure the safe availability of a contact person even over extended periods of time.
Note
OAuth usually includes a page where the end user has to confirm that a given application will now gain access to certain aspects of his account. Since all clients are manually approved upon registration and considered implicitly trusted for all users no such page is shown to the end user in pCon.login.
Important
Make sure you store/transmit any received tokens as securely as possible
Standard OAuth endpoints¶
- Authorization:
$base_url/api/oauth2/authorize
- Request tokens:
$base_url/api/oauth2/request_token
- Revoke tokens:
$base_url/api/oauth2/revoke_token
Note
Access to the authorization enpoint should be done via redirect or in a new/ popup window. Access via iframe is not supported and may not work depending on the browsers security measures.
Implementation recommendations¶
For web applications it is generally advisable to implement the authorization via the Authorization code flow in the server component of your application. Web applications that do not have a dedicated backend server can use our javascript client library to simplify implementation of the authorization code flow in browser applications.
For native (desktop) applications we also offer a C library, please contact pm_p-log@easterngraphics.com for details.
Acquire access token via refresh token¶
Some OAuth flows can return a longer lived “refresh token” that can be used to acquire access tokens with the same (or fewer) scopes as during the acquisition of the refresh token.
Important
Clients must not make any assumptions regarding the lifetime of a refresh token
See OAuth2 Section 6
POST $base_url/api/oauth2/request_token
Authorization: Basic Y2xpZW50X2lkOnNla3JpdA==
Content-type: application/x-www-form-urlencoded
grant_type=refresh_token&refresh_token=To5YDQ
==>
Content-type: application/json
{
"token_type": "Bearer",
"access_token": "asdfg",
"refresh_token": "ghjkl",
"expires_in": 3600,
"scope": "query_account"
}
Parameters¶
Parameters are encoded in the body of the post request as application/x-www-form-urlencoded
If client credentials where issued, they must be provided via Basic
authorization in the Authorization header
- grant_type:
Must be set to
refresh_token- refresh_token:
The refresh_token that was issued
- scope:
Optional. Space delimited list of required Scopes Must not include any scope that was not included at the time the refresh_token was acquired).
- client_id:
If no client credentials where provided this parameter must be set to the client id, otherwise it should be omitted.
Response¶
The response is a json object with the following properties:
- token_type:
Type of token returend (currently always Bearer)
- access_token:
The issued access token
- refresh_token:
Optional. If this is included it replaces the refresh_token used in the request.
Important
If you reduced the scopes, the new refresh_token will only allow access to these scopes.
- expires_in:
Seconds after which the access token will no longer be valid
- scope:
Optional. Space delimited list of required Scopes
For error responses and their possible causes please refer to OAuth2 Section 5.2
Revoking tokens¶
Tokens will automatically expire after a while (this also includes refresh_tokens, unless otherwise noted). However it is also possible to explicitly revoke tokens that are no longer needed
See OAuth2 Token Revocation Section 2.1
Note
Revoking a token may also revoke other related tokens (e.g. revoking an access_token may also invalidate associated refresh_token and vice versa)
POST $base_url/api/oauth2/revoke_token
Authorization: Basic Y2xpZW50X2lkOnNla3JpdA==
Content-type: application/x-www-form-urlencoded
token=To5YDQ&token_type_hint=refresh_token
Parameters¶
Parameters are encoded in the body of the post request as application/x-www-form-urlencoded
If client credentials where issued, they must be provided via Basic
authorization in the Authorization header
- token:
The token to revoke
- token_type_hint:
Optional. Specifies the type of the given token (either
access_tokenorrefresh_token)- client_id:
If no client credentials where provided this parameter must be set to the client id, otherwise it should be omitted.
Response¶
If the token was sucessfully revoked the response will have HTTP status 200.
Note
Passing an invalid token is not treated as an error
Scopes¶
Scopes define which APIs can be accessed by a given client. At the time of this writing all scopes are statically granted or rejected based on the client registration and no explicit user confirmation takes place.
The following scopes are currently available:
- query_account:
The most common permission, required to query information about the user/organization
- modify_account:
Allows changing user / account data (subject to the users permissions)
- query_receivable_pud_update_channels:
A special scope that grants only the minimum access required to use the get_package_groups API This is not needed if the application already uses the query_account scope
- create_longterm_token:
Allows a client to obtain a long term refresh token for itself.
- create_service_tokens:
Allows a client to obtain tokens on behalf of other clients. This is a highly privileged operation, therefore this scope will only be granted to trusted clients in rare cases. Please consult with pm_p-log@easterngraphics.com first if you think you will need this scope.
- query_basic_organization_info:
Allows querying a reduced set of organisation information for clients that don’t have the query_account scope
Logout¶
For clients that are pcon_session clients it is recommended to perform a logout by redirecting to the logut page: https://login.pcon-solutions.com/logout. This will implictely revoke all tokens of clients assoicated with this pcon_session. The optional url parameter next can be used to redirect back to your application e.g.: https://login.pcon-solutions.com/logout?next=https%3A%2F%2Fmyapp.example.com%2Flogged_out will redirect back to https://myapp.example.com/logged_out
Clients that do not participate in the pcon_session should instead simply revoke their tokens.