Authorization Code Flow
Basics
The authorization code flow is best suited for web applications with a client running on the server side.
Resource owners access the application via an HTML user interface rendered in a user-agent on the device used by the resource owner.
The application credentials as well as any access token issued to the application are stored on the web server and are not exposed to or accessible by the resource owner.
The application sends a user to Space via a link that also includes the scope of required resources. After the user logs in to Space, Space redirects the user back to the application using the specified redirect URI. The redirect also contains an authorization code. The application uses the authorization code to obtain an access token from Space.
To enable the flow for an application, during the application registration, select the Authorization Code Flow checkbox. The redirect URIs should be specified in the Redirect URIs field.
If you use Space SDK in your application, you can implement the flow with the help of the
SpaceHttpClient().withCallContext()
method.For more details on the flow, refer to the Authorization code flow specification.
Initial request
To start the authentication process, the application should redirect the user's browser to the authentication endpoint <Space service URL>/oauth/auth
in the following format:
${Space Service URL}/oauth/auth?response_type=code&state=${State}&redirect_uri=${Client redirect URI}&request_credentials=${Request credentials mode}&client_id=${Client ID}&scope=${Scope}&access_type={online|offline}&code_challenge={code_challenge}&code_challenge_method={code_challenge_method}
In this request:
code_challenge
is required when using the PKCE extention.code_challenge_method
is optional; defaults to "plain" if not present in the request.
For example:
To instruct Space to issue a refresh token, add the access_type=offline
parameter to your request:
To obtain an access token from Space, your application needs to provide values for a number of parameters in authorization requests. See the description of the parameters.
Handling response
If the resource owner grants the access, Space issues an authorization code and delivers it to the application by adding the following parameters to the query component of the redirection URI using the application/x-www-form-urlencoded
format:
Parameter | Description |
---|---|
code | The authorization code generated by Space. The authorization code will expire shortly after it is issued to mitigate the risk of leaks. The application must not use the authorization code more than once. If an authorization code is used more than once, Space will deny the request. The authorization code is bound to the application identifier and redirection URI. |
state | The exact value received from the application in the authorization request. |
Example: Space redirects the browser by sending the following HTTP response:
The application must ignore unrecognized response parameters.
Handling error response
If the resource owner denies the access request or if the request fails for reasons other than a missing or invalid redirection URI, Space informs the application by adding the following parameters to the query component of the redirection URI using the application/x-www-form-urlencoded
format:
- error
A single ASCII [USASCII] error code from the following:
invalid_request
— The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.unauthorized_client
— The application is not authorized to request an authorization code using this method.access_denied
— The resource owner or Space denied the request.unsupported_response_type
— Space does not support obtaining an authorization code using this method.invalid_scope
— The requested scope is invalid, unknown, or malformed.
- error_description
Human-readable ASCII [USASCII] text providing additional information, used to assist the application developer in understanding what went wrong.
Exchanging authorization code for an access token
After the application receives the code it can exchange it for an access token.
The application makes a request to the Space token endpoint by sending the following parameters using the application/x-www-form-urlencoded
format with a character encoding of UTF-8 in the HTTP request entity-body:
POST /oauth/token
Host: ${Space Service URL}
Accept: application/json
Authorization: Basic ${base64(${Client ID} + ":" + ${Client secret})}
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&code=${Code received on a previous step}&redirect_uri=${Client redirect URI}&code_verifier={code_verifier}
In this request:
code_verifier
is required when using the PKCE extension.client_id
is required when using the PKCE extension for Public Clients (untrusted services) and when Auth Header is omitted.
Example:
See the description of the parameters.
Handling Access Token Response
If the access token request is valid and authorized, Space issues an access token. If the request has failed or is invalid, the Space server returns an error response.
Example of a successful response:
Parameters
- response_type
Specifies the grant type in an OAuth 2.0 request. Set value to
code
- state
An identifier for the current application state. For example, it can be a key for a local storage object that contains information about the location of the current user in the application.
- redirect_uri
A URI in your application that can handle responses from Space.
- request_credentials
A parameter that determines whether the user should be asked to log in. The following values are valid:
skip
— use when the application allows anonymous access.If the user is already logged in to Space, the user is granted access to the application.
If the user is not logged in to Space and the guest account is not banned, the user is granted access to the application as a guest.
If the user is not logged in to Space and the guest account is banned, the user is redirected to the login page.
silent
— same asskip
, but redirects the user to the application in all cases. If the guest account is banned, the user is redirected to the application with an authentication error.required
— logs the user out of Space and redirects them to the login page. Use as a response to a logout request in the application.default
— use when the application does not allow anonymous access.If the user is already logged in to Space, the user is granted access to the application.
If the user is not logged in to Space, the user is redirected to the login page.
- client_id
The ID assigned to your application when you register it in Space. To get the client ID, go to
and choose your application from the list.
- client_secret
The private identifier assigned to your application when you register it in Space. To get the client secret, go to
and choose your application from the list.
- scope
A space separated list of rights required to access specific resources in Space.
The rights are grouped in four categories: Global, Profile, Team, Project. Use the following syntax to specify the rights (shown here in BNF notation):
<SCOPE> ::= <ALL> | <TOKEN_LIST> <ALL> ::= '**' <TOKEN_LIST> ::= <TOKEN> (' ' <TOKEN>)* <TOKEN> ::= <GLOBAL_PERMISSIONS_TOKEN> | <ENTITY_PERMISSIONS_TOKEN> <GLOBAL_PERMISSIONS_TOKEN> ::= <PERMISSIONS> <ENTITY_PERMISSIONS_TOKEN> ::= <ENTITY> ':' <PERMISSIONS> <ENTITY> ::= 'Team' | 'Project' | 'Profile' | 'etc.' <PERMISSIONS> ::= <ALL_PERMISSIONS> | <PERMISSION_LIST> <ALL_PERMISSIONS> ::= '*' <PERMISSION_LIST> ::= <PERMISSION> (',' <PERMISSION>)*Wildcards are accepted. For global rights, category is omitted.
Example:
AddNewProfile,AddNewTeam Team:EditTeam Profile:EditAbsences,EditLanguages Project:*The rights you specify in
scope
should be first added to the list of requested rights and authorized for your application in Space.- access_type
Indicates whether the application requires access to Space when the user is not online. Allowed values:
online
(used by default) andoffline
. If the application requires refreshing access tokens when the user is not online, use theoffline
value. In this case Space issues a refresh token for the application the first time it exchanges an authorization code for a user. Refer to the Refresh Token page for more information.- code_verifier
A high-entropy cryptographic random string that uses the unreserved characters
[A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~"
, with a minimum length of 43 characters and a maximum length of 128 characters.The client creates a code verifier for each OAuth 2.0 Authorization Request.
It is recommended that the output of a suitable random number generator be used to create a 32-octet sequence. The octet sequence is then base64url-encoded to produce a 43-octet URL safe string to use as the code verifier. For details, see Section 4.1 of RFC7636.
- code_challenge
A code challenge is derived by client from the code verifier using either
plain
orS256
transformations:plain
:code_challenge = code_verifier
S256
:code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))
For details, see Section 4.2 of RFC7636.
- code_challenge_method
This parameter defines the type of transformation used to create the
code_challenge
: eitherplain
orS256
.If the client is capable of using
S256
, it must useS256
. Clients are permitted to useplain
transformation only if they cannot supportS256
for some technical reason.For details, see Section 4.2 of RFC7636.