Integration Server 10.11 | Built-In Services Reference Guide | OAuth Folder | Summary of Elements in this Folder | pub.oauth:authorize
 
pub.oauth:authorize
WmPublic. Initiates an authorization request from a client application to the Integration Server authorization server.
Input Parameters
response_type
String The grant type preferred by the client. This parameter informs the authorization server how to respond to the client. Set to:
*code for the authorization code grant. When set to code, the response from authorization server must include an OAuth authentication code the client can exchange for an access token.
*token for an implicit grant type. When set to token, the response from authorization server includes an OAuth access token for the client.
For more information about grant types, see Usage Notes.
client_id
String The client identifier generated by the authorization server when the client application is registered. The client_id is used to authenticate the client to the authorization server.
redirect_uri
String. Optional. The URI that the authorization server will use to redirect the client when the client is authorized.
This parameter is required if the client is registered with more than one redirect URI. The value for redirect_uri must match one of the client's registered redirect URIs.
scope
String Optional. The name of the scope associated with the client. The scope defines the level of access requested by the client.
Specify the name of one or more scopes. Use a space to separate the name of the scopes. For example:
scope1 scope2 scope3
The scopes you specify must already exist on the authorization server. For information about creating a scope, see the section Defining Scopes in the webMethods Integration Server Administrator’s Guide. Defining Scopes..
code_challenge
String Optional. The transformed version of the code_verifier created by the client application.
When Integration Server requires PKCE for public clients using the authorization code grant type, the code_challenge input parameter is required. Integration Server requires PKCE for a public client when the Require PKCE option on the Security > OAuth page is set to yes.
code_challenge_method
String Optional. The method used to transform the code_verifier created by the client application. Set to:
*plain. This is the default.
*S256
When code_challenge_method is plain, the code_challenge value is the same as the code_verifier.
state
String. Optional. A unique string used to maintain the state between the request and callback. When the authorization server redirects the user to the redirect_uri, the value for state will be included in the response. Software AG recommends using this parameter to protect against cross-site request forgery (CSRF) attacks.
Output Parameters
None.
Usage Notes
The pub.oauth:authorize service is the authorization endpoint for the Integration Server acting as the authorization server. The authorization endpoint URL is:
https://host:port/invoke/pub.oauth/authorize
This service must be invoked using HTTPS unless the Require HTTPS setting on the Security > OAuth > Edit OAuth Global Settings page is disabled.
When you register a client, you must consider the grant type the client should use to obtain an access token. Integration Server supports the following grant types with the pub.oauth:authorize service:
*Authorization code. Requires the client to authenticate to the authorization server before obtaining an access token. The authentication code supplied by the authorization server is included in the redirection URI. The client can refresh an expired token. To implement an authorization code grant, set the response_type to code.
*Implicit. Less secure than the authorization code grant. It does not require the client to authenticate to the authorization server. The authentication server includes the access token in the redirection URI. The client cannot refresh an expired token. To implement an implicit grant, set the response_type to token.
If the client calls the pub.oauth:authorize service with a response_type of password or client_credentials, the service rejects the request with an invalid_request OAuth error.
Authentication code is not persisted in the cache. If Integration Server is restarted after the authorization code is issued but before the access token is requested, Integration Server will reject the request for the access token.
The code_challenge input parameter is required for a public client when the Require PKCE option on the Security > OAuth page is set to yes and the client identifies authorization code grant type as the preferred grant type (i.e., response_type is set to code).
Integration Server provides the com.softwareag.util.PKCE.createCodeVerifier method for creating a code_verifier value and the com.softwareag.util.PKCE.createCodeChallenge method for transforming a code_verifier value into a base64-encoded, SHA-256 hash to use as the value for code_challenge. For more information, see the webMethods Integration Server Java API Reference.