OAuth2
fylr uses OAuth2 for authentication.
Last updated
fylr uses OAuth2 for authentication.
Last updated
User authentication in a fylr instance is only possible by receiving an Access Token using one of the implemented OAuth2 flows.
After a successful login of a user, the process will return a response that contains an access_token. This must be used to authenticate all following requests to the fylr API.
Include the following HTTP header in the request:
Include the following parameter in the request URL:
The following descriptions of the different OAuth2 flows use my-client and my-secret as placeholders for configured Client IDs and Client Secrets. Replace these with the required OAuth2 client information of the fylr instance.
These need to be configured in the fylr instance.
Configure the pair(s) of Client ID and Secret in the fylr.yml:
The default clients in fylr are public and thus do neither need nor have a secret.
This flow requires a Client ID and Secret, as well as a fylr login and password for each user. This flow offers a high level of security.
Call the OAuth2 Authentication API of fylr
GET fylr-instance/api/oauth2/auth
Query Parameters
auth_method*
string
fixed value: "auto"
access_type*
string
fixed value: "offline"
scope*
string
fixed value: "offline"
response_type*
string
fixed value: "code"
state*
string
Client State String (min. 8 characters), for example: "Authorization_Code_Grant_Login"
client_id*
string
Client ID of the fylr Instance: "my-client"
This redirects to the fylr login page. The user enters login and password directly into fylr.
This flow requires to implement a local HTTP server that can handle the callback from fylr. The URL for the callback must also be included in the fylr.yml (redirectURIs) and must be tied to your Client configuration.
fylr calls
This callback must handle a GET request. fylr includes these URL parameters:
Call the OAuth2 Authentication API of fylr
GET my-callback-server/oauth2/callback
Query Parameters
state*
string
Client State, this is to identify the callback. Same as above
code*
string
Authorization Code. This needs to be stored and used in the following requests
Call the OAuth2 Token API of fylr
POST fylr-instance/api/oauth2/token
Query Parameters
grant_type*
string
fixed value: "authorization_code"
state*
string
Client State, same as above
client_id*
string
Client ID of the fylr Instance: "my-client"
client_secret*
string
Client Secret of the fylr Instance: "my-secret"
code*
string
Authorization Code from fylr callback
If the Client ID, Secret and the Authorization Code are correct, fylr will return a JSON object in the response with the following values:
access_token
Access Token
refresh_token
Refresh Token
token_type
"bearer"
scope
"offline", same as above
expires_in
Time until the Access Token expires, in seconds
The Code Verifier is a random string consisting of the characters A-Z, a-z, 0-9, -, ., _, ~ with a length between 43 and 128 characters.
The Code Challenge is the SHA256 hash of the Code Verifier encoded in Base64-URL format.
For Step 1, these parameters are added to the URL:
code_challenge
Generated Code Challenge
code_challenge_method
"S256"
fixed value
For Step 3, this parameter is added to the URL:
code_verifier
Generated Code Verifier
In this step, fylr (the authorization server) checks if the Code Verifer matches the Code Challenge from Step 1.
This flow can be used to directly log into fylr with the user login and password
Call the OAuth2 Token API of fylr
POST fylr-instance/api/oauth2/token
Query Parameters
grant_type*
string
fixed value: "password"
scope*
string
fixed value: "offline"
client_id*
string
Client ID of the fylr Instance: "my-client"
client_secret*
string
Client Secret of the fylr Instance: "my-secret"
username*
string
fylr Login of the user
password*
string
fylr Password of the user
If the Client ID, Secret and user login and password are correct, fylr will return a JSON object in the response with the following values:
access_token
Access Token
refresh_token
Refresh Token
token_type
"bearer"
scope
"offline", same as above
expires_in
Time until the Access Token expires, in seconds
This flow works without a Client Secret. It is not possible to refresh or revoke the Access Token.
Using this flow is not recommended!
Call the OAuth2 Authentication API of fylr
GET fylr-instance/api/oauth2/auth
Query Parameters
response_type*
string
fixed value: "token"
auth_method*
string
fixed value: "auto"
scope*
string
fixed value: "offline"
access_type*
string
fixed value: "offline"
state*
string
Client State String (min. 8 characters), for example: "Implicit_Grant_Login"
client_id*
string
Client ID of the fylr Instance: "my-client"
This flow requires to implement a local HTTP server that can handle the callback from fylr. The URL for the callback must also be included in the fylr.yml (redirectURIs) and must be tied to your Client configuration.
fylr calls
This callback must handle a GET request. fylr includes these URL parameters:
Call the OAuth2 Authentication API of fylr
GET my-callback-server/oauth2/callback
Query Parameters
loc_hash*
string
quoted URL parameters
The loc_hash parameter is itself a list of URL parameters that need to be unquoted and split into key value pairs:
access_token
Access Token
token_type
"bearer"
scope
"offline", same as above
state
"Implicit_Grant_Login", same as above
expires_in
Time until the Access Token expires, in seconds
This flow works without a fylr user login and password. The Access Token can not be used to identify a specific user. All fylr api endpoints which require a authenticated user can not be used.
Using this flow is not recommended!
Call the OAuth2 Token API of fylr
GET fylr-instance/api/oauth2/token
Query Parameters
grant_type*
string
fixed value: "client_credentials"
state*
string
Client State String (min. 8 characters), for example: "Implicit_Grant_Login"
client_id*
string
Client ID of the fylr Instance: "my-client"
client_secret*
string
Client Secret of the fylr Instance: "my-secret"
If the Client ID and Secret are correct, fylr will return a JSON object in the response with the following values:
access_token
Access Token
token_type
"bearer"
scope
"offline", same as above
expires_in
Time until the Access Token expires, in seconds
Alternatively, add the Client ID and Secret pair(s) in the .
All of the following flows are implemented in fylr. They offer different levels of security. Each flow requires a different amount of complexity to implement it in your client application. Depending on your needs choose your preferred implementation. We recommend using the or the flow.
External documentation:
External documentation:
This is an extension of the flow. To enhance the security a Proof Key for Code Exchange (PKCE) is included in the requests. All other parameters and keys are the same as in the flow.
The client needs to generate a Code Verifier and a Code Challenge according to the standard.
External documentation:
External documentation:
External documentation: