OAuth2

fylr uses OAuth2 for authentication.

User authentication in a fylr instance is only possible by receiving an Access Token using one of the implemented OAuth2 flows.

Using the Access Token

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.

Header based authentication

Include the following HTTP header in the request:

"authorization: Bearer <access_token>"

URL based authentication

Include the following parameter in the request URL:

?access_token=<access_token>

Configuring Client ID and Secret

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 config file fylr.yml:

fylr:
  services:
    api:
      oauth2Server:
        clients:
          my-client:
            secret: 'my-secret'
            redirectURIs:
              - http://my-callback-server/oauth2/callback

The default clients in fylr are public and thus do neither need nor have a secret.

Alternatively, add the Client ID and Secret pair(s) in the Base Configuration.

OAuth2 Flows

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 Authorization Code Grant or the Password Grant flow.

Authorization Code Grant

External documentation: https://www.oauth.com/oauth2-servers/server-side-apps/authorization-code/

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.

Step 1: client calls fylr

Call the OAuth2 Authentication API of fylr

GET fylr-instance/api/oauth2/auth

Query Parameters

Name	Type	Description
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"

200 OK

This redirects to the fylr login page. The user enters login and password directly into fylr.

400 Error

Problems with the parameters, for example an invalid Client ID

Step 2: callback from fylr to the local HTTP server

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

my-callback-server/oauth2/callback

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

Name	Type	Description
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

Step 3: client validates Authorization Code

Call the OAuth2 Token API of fylr

POST fylr-instance/api/oauth2/token

Query Parameters

Name	Type	Description
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

200 OK

400 Error

If the Client ID, Secret and the Authorization Code are correct, fylr will return a JSON object in the response with the following values:

Key	Description
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

Authorization Code Grant with PKCE Code Challenge

External documentation: https://www.oauth.com/oauth2-servers/oauth-native-apps/pkce/

This is an extension of the Authorization Code Grant 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 Authorization Code Grant flow.

The client needs to generate a Code Verifier and a Code Challenge according to the RFC7636 standard.

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:

Parameter	Value	Description
code_challenge		Generated Code Challenge
code_challenge_method	"S256"	fixed value

For Step 3, this parameter is added to the URL:

Parameter	Value	Description
code_verifier		Generated Code Verifier

In this step, fylr (the authorization server) checks if the Code Verifer matches the Code Challenge from Step 1.

Password Grant

External documentation: https://www.oauth.com/oauth2-servers/access-tokens/password-grant/

This flow can be used to directly log into fylr with the user login and password

Step 1: log into fylr with user login and password

Call the OAuth2 Token API of fylr

POST fylr-instance/api/oauth2/token

Query Parameters

Name	Type	Description
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

200 OK

400 Error

Problems with the parameters, for example an invalid Client ID

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:

Key	Description
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

Implicit Grant

External documentation: https://www.oauth.com/oauth2-servers/single-page-apps/implicit-flow/

This flow works without a Client Secret. It is not possible to refresh or revoke the Access Token.

Using this flow is not recommended!

Step 1: request a token from fylr

Call the OAuth2 Authentication API of fylr

GET fylr-instance/api/oauth2/auth

Query Parameters

Name	Type	Description
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"

200 OK

400 Error

Problems with the parameters, for example an invalid Client ID

Step 2: callback from fylr to the local callback

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

my-callback-server/oauth2/callback

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

Name	Type	Description
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:

Key	Description
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

Client Credential Grant

External documentation: https://www.oauth.com/oauth2-servers/access-tokens/client-credentials/

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!

Step 1: request a token from fylr

Call the OAuth2 Token API of fylr

GET fylr-instance/api/oauth2/token

Query Parameters

Name	Type	Description
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"

200 OK

400 Error

Problems with the parameters, for example an invalid Client ID

If the Client ID and Secret are correct, fylr will return a JSON object in the response with the following values:

Key	Description
access_token	Access Token
token_type	"bearer"
scope	"offline", same as above
expires_in	Time until the Access Token expires, in seconds