The outbound service project calls a RESTful service secured with OAuth the 2.0 standard. When you import an OpenAPI Specification to an ePortal Outbound Service project with OAuth 2.0 authorization, a new section is created in the configuration file with the same security key used in the specification.
The following files show an example of the security scheme section in the specification file and the equivalent values generated by the outbound project in the configuration file.
OpenAPI Specification File
securitySchemes:
oauth2sample:
type: oauth2
flows:
password:
tokenUrl: /oauth/token
scopes:
read:LH Read API: read access
write:LH Write API: write access
delete:LH Delete API: delete access
clientCredentials:
tokenUrl: /oauth/token
scopes:
read:LH Read API: read access
write:LH Write API: write access
delete:LH Delete API: delete access
security:
- oauth2sample: [ ]
Outbound Service Configuration File
"SecuritySchemes": {
"oauth2sample": {
"OAuth2": {
"clientCredentials": {
"OAuth2_Request": {
"Token_Endpoint": "https://baseurl/oauth/token",
"Client_ID": "",
"Client_Secret": "",
"Scopes": {
"read:LH Read API": "read access",
"write:LH Write API": "write access",
"delete:LH Delete API": "delete access"
}
}
},
"password": {
"OAuth2_Request": {
"Token_Endpoint": "https://baseurl/oauth/token",
"User_ID": "",
"User_Password": "",
"Client_ID": "",
"Client_Secret": "",
"Scopes": {
"read:LH Read API": "read access",
"write:LH Write API": "write access",
"delete:LH Delete API": "delete access"
}
}
}
}
}
The COBOL application calls the ePortal proxy service, which then makes a call to the external REST API to process the request. To make the external API call, the ePortal proxy service cannot make a request for your credentials during runtime. Therefore, the OAuth 2.0 flows that supports outbound service calls have the following restrictions.
Client Credentials: In the Client Credentials flow, the ePortal proxy service (OAuth client) provides client ID and client secret to retrieve an OAuth token.
Resource Owner Password Credentials: In the Resource Owner Password Credentials flow, the ePortal proxy service provides a user name and password to retrieve an OAuth token.
Configuring OAuth 2.0 in Outbound Service
When you import an OpenAPI specification that supports OAuth 2.0, an equivalent section is generated in the configuration.json file under the Outbound Web Service project.
Client Credentials Flow
To call a service that uses client credentials flow, you should set the values for the client ID and the client secret in the configuration section.
Note: You can obtain the client ID and client secret from the RESTful service provider.
"SecuritySchemes": {
"oauth2sample": {
"OAuth2": {
"clientCredentials": {
"OAuth2_Request": {
"Token_Endpoint": "https://baseurl/oauth/token",
"Client_ID": "",
"Client_Secret": "",
"Scopes": {
"read:LH Read API": "read access",
"write:LH Write API": "write access",
"delete:LH Delete API": "delete access"
}
}
}
}
}
Password Grant Flow
To call a service that uses password grant flow, set the values for the user ID, user password, client ID, and the client secret in the configuration section.
Notes:
You can obtain the client ID and client secret from the RESTful service provider.
It is recommended to handle the user-specific parameters such as user ID and user password using the COBOL application.
"SecuritySchemes": {
"oauth2sample": {
"OAuth2": {
"password": {
"OAuth2_Request": {
"Token_Endpoint": "https://baseurl/oauth/token",
"User_ID": "",
"User_Password": "",
"Client_ID": "",
"Client_Secret": "",
"Scopes": {
"read:LH Read API": "read access",
"write:LH Write API": "write access",
"delete:LH Delete API": "delete access"
}
}
}
}
}
Configuration file updates after receiving the token from the authorization server.
"SecuritySchemes": {
"auth": {
"OAuth2": {
"clientCredentials": {
"OAuth2_Request": {
"Token_Endpoint": "https://baseurl/oauth/token",
"Client_ID": "t8xfkq9tuw92bykd54w968bz",
"Client_Secret": "q5aUN5N8fG",
"Scopes": {
"read:LH Open API": "read access"
}
},
"OAuth2_Response": {
"Access_Token": "5dkk8a77gta9k7ms2uzav9z3",
"Token_Type": "Bearer",
"Expires_In": 129600
}
}
}
}
}
In both the flows, when the COBOL application calls the ePortal Service proxy, it first invokes the authorization server to obtain the access token and stores it in the configuration file under the OAuth2_Response section. The access token is returned as part of the Response COBOL Payload. The access token, token expiry, and other details are stored in the configuration file for caching purpose.
Note: By default, the access token information is sent to the resource server in the query parameter. To specify the location, mention "in" parameter and the location in which the access token needs to go in the OpenAPI specification file.
Access Token Expiry
The Outbound Web Service stores new access tokens in the configuration file. Within the expiry period, the web service reuses the access tokens for API requests with matching OAuth-related information from the configuration file. Once expired, the access tokens are not used.
When an access token expires, 401 HTTP response code is returned to the Outbound Web Service. In this case, the Outbound Web Service requests a new access token from the authorization server and stores it in the configuration file, and then sends the API request with the renewed access token to the request endpoint.