OAuth 2.0
FlowForce Server enables you to create credential objects that are OAuth 2.0 authorization details. You can use OAuth 2.0 credentials in FlowForce Server jobs that call Web services where OAuth 2.0 is required. Users can view and access OAuth credentials only if they have the corresponding permissions. For details, see How Permissions Work.
To create an OAuth 2.0 credential, navigate to the container in which you want to store the credential, click Create | Create Credential, switch to OAuth 2.0 in the Credential Type field, and fill in the credential fields (described below).
About OAuth 2.0 workflow
OAuth stands for Open Authorization and is an open-standard authorization framework that allows applications to access a set of user resources on behalf of a user. The broad procedures associated with the OAuth 2.0 workflow are described below:
1.A third-party application (Client) registers with an authorization server. The authorization server issues a client ID and, if applicable, a client secret.
2.The Client indicates a redirection URI, to which a User will be redirected after granting or denying permission to the Client.
3.The User initiates an action in the client application, which requires access to the User's resources. For example, the User may want to log into the client application, using their Facebook account.
4.The Client sends a request to the authorization server and redirects the User to the authorization endpoint of the authorization server, where the User logs in and grants or denies permission to the Client. The Client's request to the authorization server contains the client ID, requested privileges, and the redirect URI.
5.If the the User has granted permission to the Client, the Client receives an authorization grant and exchanges the user credentials or authorization details (this depends on the grant type) for an access token and, if applicable, a refresh token.
6.The Client then uses the access token to access the User's resources on the resource server.
7.If the access token has expired, the Client can use the refresh token to continue using the User's resources without the User's re-authentication. Whether the Client uses the refresh token or not depends on the grant type you have selected. See the Access Token property below for more details.
Available parameters
The fields associated with an OAuth 2.0 credential object are listed below. To obtain these values, you must first register with a Web service provider (e.g., Google API Console, Facebook API, Bitbucket API).
OAuth grant types determine how a client application (in this case, FlowForce Server) communicates with the OAuth service and gets an access token. The following grant types are supported:
•Resource Owner Password Credentials
Depending on the selected grant type, different properties become available. For more information about each property, see the options below.
|
An authorization endpoint is a URI to which a resource owner (i.e., a user) is redirected to initiate authentication, consent, and authorization. The authorization endpoint is provided by an authorization server. When FlowForce Server wants to get access to the user's resources, FlowForce Server redirects the user's browser to the authentication endpoint. After authentication, the user decides whether to grant or deny permission to FlowForce Server. After the authorization decision has been taken, the authorization server redirects the user to the path specified in the Redirect URI parameter.
You can obtain the authorization endpoint after registering with the Web service provider.
|
A token endpoint is a location where a client application (in this case, FlowForce Server) makes a request to get an access token in exchange for certain credentials or authorization details. You can get this value after registering with the Web service provider.
|
A client ID is a unique public identifier of a client application (FlowForce Server in this case). The client ID is issued by an authorization server. The authorization server uses the client ID and secret (described below) to verify the client's identity. You can get this value after registering with the Web service provider.
|
A client secret is a confidential bit of information that a client application (in this case, FlowForce Server) uses for authentication. The client secret is issued by an authorization server. The authorization server uses the client ID and secret to verify the client's identity. The client secret helps prevent unauthorized applications from impersonating clients and accessing users' resources. You can get the client secret after registering with the Web service provider.
|
A scope defines the extent of access to a user's resources that a client (in this case, FlowForce Server) requests (e.g., read and write privileges). You can get this value after registering with the Web service provider.
|
An access token is a piece of data that the client (i.e, FlowForce Server) receives from an authorization sever after the authorization process has been completed successfully. The access token allows FlowForce Server to access the user's resources. The FlowForce Server job will be executed successfully only if the resource server determines that the access token is correct and valid. To obtain this value manually the first time you create an OAuth credential, provide all the authorization details (except for the Refresh token value) and click Authorize and Save.
How tokens are refreshedThe access token expires after a period of time set by the Web service provider. Depending on the grant type you have selected, the procedures for refreshing tokens may vary. If you have selected the Authorization Code or Implicit grant type and the token has expired, FlowForce Server will request a new one from the authorization server, using the Refresh token value (see below).
If you have selected the Client Credentials or Resource Owner Password Credentials grant type and the token has expired, FlowForce Server will try to obtain a new token, by sending a request to the token endpoint. For the token to be obtained successfully, all the relevant authorization details must be provided (e.g., client ID, client secret, etc.).
|
Access tokens (see above) are short-lived for security reasons. The expiration time of an access token is determined by an authorization server. If the authorization server supports refresh tokens, it will issue a refresh token together with an access token during the authorization process. For details about how tokens are refreshed, see Access Token above.
|
The Username and Password fields become available when you select the Resource Owner Password Credentials grant type. In this grant type, the client application directly exchanges the user's credentials (username and password) for an access token and, optionally, for a refresh token. As soon as the client gets the user's credentials, the client sends a POST request to the authorization server. If the request is successful, the authorization server will issue an access token that the client can use to access the user's resources.
|
A redirect URI is a location at which you access FlowForce Server and to which the authorization sever redirects the user after the user has granted or denied permission to the client (i.e, FlowForce Server). It is also the location to which the authorization server sends an authorization code that is required to get an access token. This field is filled automatically by FlowForce Server.
Make sure to copy the redirection URI and add it to the list of allowed redirection URIs on the platform where you register your client application. Since it is possible to access FlowForce Server from different addresses and ports, make sure to add all of these URIs to the list of allowed redirection URIs
|
Client authentication refers to the process of verifying the identity of a client application (i.e., FlowForce Server) by an authorization server. The authorization server then decides whether to grant or deny the client permission to get an access token form the token endpoint. Client authentication ensures that the authorization server issues an access token only to a legitimate client.
Most OAuth 2.0 authorization servers require that authentication details be submitted in the POST request AUTH header. Some OAuth 2.0 authorization servers accept authentication details only in the body of the POST request. Depending on the requirements of the authorization server, select the relevant option from the drop-down list.
|
For more information about Allow usage for options, see Credential Type: Password. For an OAuth 2.0 credential that you plan to use for HTTP, make sure that the Allow usage for HTTP check box is selected. Otherwise, the job will fail.
After you have selected the relevant grant type and filled in all the necessary fields, you can simply save the credential (the Save button) or initiate authorization and save the credential object (the Authorize and Save button). When you select the Authorize and Save option, FlowForce Server will redirect the browser to the service authorization page (only relevant to the Authorization Code and Implicit grant types) or will attempt to get an access token from an external service and save the access token together with the changes to the credential object. Once the access token and, potentially, a refresh token have been obtained, the credential page will be refreshed and will inform you that authorization has been granted.