How a custom command line application obtains an access token from UMS SSO

Because a custom command line application cannot redirect a user to a browser UI for authentication, such applications can use the Resource Owner Password Credentials flow to obtain an access token from User Management Service (UMS) single sign-on (SSO) that can be used to invoke an OAuth 2.0 protected REST API.

Understanding the Resource Owner Password Credential flow

In the Resource Owner Password Credentials flow, resource owner credentials, such as username and password, are used directly to obtain an access_token. The custom command line application therefore initially needs to obtain credentials from the resource owner (the end user). It can then invoke UMS SSO, authenticate as a registered client application and exchange the user's username and password combination for an access_token. This flow can also be used with client types other than command line, but this is the most typical usage scenario.

Design considerations for the custom command line application

The custom command line application must register with UMS SSO as an OIDC Relying Party, for example:
```
curl -v -k -s -X POST -H "Content-Type:application/json" -u "umsadmin:passw0rd" -d @- "https://<ums-host>/oidc/endpoint/ums/registration" <<+++
{
  "scope": "openid",
  "preauthorized_scope": "openid",
  "introspect_tokens": true,
  "client_id": "customApp",
  "client_secret": "passw0rd",
  "client_name": "customApp",
  "grant_types": ["password"],
  "response_types": [ "token"]
}
+++
```
Where
- passw0rd is an example client_secret to authenticate as the custom command line application to UMS - make sure that you use a much stronger secret
- customApp is a human-readable identifier for your custom command line application
- grant_types must be set to “password”
- response_types must be set to “token”
Then the app can obtain an access token. For example:
```
curl -k -X POST -u "customApp:passw0rd" -d "grant_type=password&scope=openid&username=user_name&password=user_password" "https://ums-host/oidc/endpoint/ums/token"
```
Where
- option -u "customApp:passw0rd" is used by the client to authenticate with UMS, it is the combination of the values for client_id and client_secret that you registered in the previous step.
- grant_type must be set to "password".
- user_name and user_password are the credentials of the resource owner user name for whom the access token is being requested.
- ums-host is the hostname of the UMS server.
The response contains the access token, access_token, for example:
```
{
  "access_token": "uEsdnucnBtjt8llTYQDqKHxcPF7a06YLX1IbzQH8",
  "token_type": "Bearer",
  "expires_in": 7199,
  "scope": "openid"
}
```
The custom command line application uses the access_token in the authorization header of the request to invoke the OAuth 2.0 protected REST API. For example:
```
curl -k -s -H "Authorization: Bearer $access_token" https://my.server:9443/rest/bpm/wle/v1/user/current
```