Syntax:

com.ibi.agents.XDOAuth2Agent

Description:

This service emits an HTTPS request authenticated by OAuth 2.0 using the credentials of a Google service account.

OAuth 2.0 is described in RFC6749 and RFC6750. It is an authorization framework that enables an application to obtain access to an HTTP resource. The role of the client and the resource owner are separate. The client does not use the resource owner credentials. Instead, it requests an access token from a trusted authorization server. The client presents the token together with the request to the resource server which grants access if the token is valid.

The OAuth 2.0 Authentication service manages the creation and renewal of access tokens by communicating with the authorization server. If it obtains a valid access token, it incorporates the token with the outgoing HTTPS request to make the authenticated call.

When OAuth 2.0 is used interactively, the user is often redirected to a consent screen to enter his credentials. Since the iSM service operates in a server-to-server scenario, there is no consent screen involved. Instead, the client provides its credentials with the private key associated with a Google service account. The authorization server will be accessed at the same location as the resource server.

When obtaining a token, the client must specify the scope of the access requested. For example, there could be a scope for read-only and another for read-write permissions. It is also possible to request multiple scopes in a single access token.

The scopes are not standardized. The resource servers are free to define the scopes that make sense for their application. The documentation of the resource server API will make it clear which OAuth 2.0 scopes it supports. It remains the responsibility of the application designer to request and use the appropriate scopes.

Parameters:

The following table lists and describes the parameters for the OAuth 2.0 Authentication service.

Parameter	Description
HTTP Client Provider	HTTP Client provider that manages connections for this emitter.
Destination URL	URL where the request will be addressed. The URL should be fully specified, including the HTTPS scheme.
HTTP Method	POST sends the current document as a request entity. GET and HEAD will send a request to the configured URL.
Content Type	Content type for the HTTP request to be sent by this emitter.
Request Header Namespace	Special register namespace from which HTTP headers for the outgoing request will be taken. Select Default Namespace to send the HDR type registers with no namespace prefix, or supply a namespace prefix here. None means that no special registers will be sent as HTTP headers.
Response Header Namespace	Special register namespace into which HTTP headers from the incoming response will be saved. Select Default Namespace to create special registers with no namespace prefix, or supply a namespace prefix here.
Scopes	Determines which services the application requests access to. Select one from the list or enter a space-separated list of scopes.
Project ID	Value of the x-goog-project-id header.
Service Account Email	Email address of the service account.
KeyStore Provider	Provider for the keystore containing the service account private key.
Private Key Alias	Alias of the service account private key within the keystore.
Private Key Password	Password for the private key. If left blank, the password for accessing the keystore will be used.

The HTTP Client provider can be defined on the pooling providers page in the iWay Service Manager console. Google recommends that OAuth 2.0 should always be used with HTTPS, therefore the HTTP Client provider should specify an SSLContext Provider.

The authenticated request will be sent to the Destination URL. The service will access the authorization server at the same location to obtain access tokens. The HTTP method specifies the type of request: GET, PUT, POST, HEAD, PATCH or DELETE. The Content Type parameter specifies the content type of the authenticated request.

If additional headers are needed, they can be declared as HDR registers in the Request Header Namespace. The default value is none, which means there is no Request Header Namespace and no extra headers are added.

The headers of the HTTP response are stored as special registers in the specified Response Header Namespace.

The Scopes parameter specifies the access scope requested from the authorization server. The access token returned will grant those scopes. For example, if the scope in the token is read-only-access and a write operation is attempted, the resource server will reject the call because the scope is not sufficient. The scopes are application specific. For more information, see the resource server API documentation to learn which scopes it supports.

The Project ID is optional. When present, it specifies the value of the x-goog-project-id header. In the cloud platform of Google, a Project consists of a set of users, a set of APIs, and billing, authentication, and monitoring settings for those APIs.

The Service Account Email acts like a user name for a service account. It looks like an email address but there is no actual email involved. The credential for the service account is a private key. The KeyStore Provider is the name of the iSM keystore provider that holds the private key. The Private Key Alias and the Private Key Password are the alias and password of the private key entry within the Keystore.

Edges:

The following table describes the edges that are returned by the OAuth 2.0 Authentication Service.

Edge	Description
Success	The request message was successfully sent and the response received.
fail_parse	An iFL expression could not be evaluated.
fail_operation	The operation could not be completed successfully.

Example:

This example shows how to retrieve a document from the Google Cloud Storage using the OAuth 2.0 Authentication Service.

Google Cloud Storage is a service to store data in the cloud and retrieve it later. It has a RESTful API, authenticated with OAuth 2.0. The equivalent of a file is called an object. Objects are stored in folders called buckets. Buckets are like directories, except they are not hierarchical. Every bucket exists in a single namespace shared by all users of the service. The slash ( / ) character is invalid in a bucket name but is accepted in an object name.

The Google Cloud platform supports multiple varieties of credentials. For server to server applications, a service account must be used. This is a name associated with a public key. The client proves his identity by encrypting with the private key which is kept secret. Service accounts are tied to a specific Google project. They are created in the Google Developer Console. Google chooses the service account name and creates the public-private key pair automatically. The private key is downloaded at the time the service account is created.

The Google Developer Console may change without notice. Proceed with the following steps:

From the following website, https://console.developers.google.com:

1. Sign in with your Google account or create a new google account on the sign-in page if you do not already have one. This is your regular Google account, not a service account yet.
2. Create a new Google project, specify the project name and the project ID, and then write down the project ID.
3. In the left menu, select APIs & auth and then click on APIs. Ensure that the Google Cloud Store is set to ON.
4. In the left menu, select APIs & auth, click Consent. and then proceed to the next step. The consent screen is not used in this example, but it must be selected and meet the requirements of Google.
5. Enter any Product Name and click Save.
6. In the left menu, select APIs & auth, click Credentials, and select Create new Client ID.
7. In the dialog that appears, select Service Account and click Create client ID. This will download a PKCS12 Keystore containing the private key of this service account.
8. Save the keystore in a convenient location and write down the keystore password shown on the screen, for example, notasecret.
9. Record the email address of the service account shown on the screen. The email address will look similar to the following:

   298643775104-81neakmsco3agrv956tl8inu8ci7oedl@developer.gserviceaccount.com

10. In the left menu, select Billing & settings, then enable the billing, and fill in the financial information.
11. In the left menu, click Storage, select Cloud Storage, Storage Browser and then click Create a bucket, and enter the bucket name. This must be a unique name among all buckets in the Google Cloud Storage. A good practice is to use your bucket name with your domain name changing the period with a dash. For example: test99-example-com
12. Click Upload and select a file to store in the Google Cloud Storage, then write down the name of the bucket and the file name in the bucket.
13. Go to https://pki.google.com and download the CA certificate for Google Internet Authority G2. This will be used to create a truststore.

    The following information will be available:

    • The project ID.
    • The Keystore containing the private key.
    • The Keystore password.
    • The service account email address.
    • The bucket name.
    • The object name in the bucket.
    • The certificate for Google Internet Authority G2.
14. Import the Google CA certificate into a Java Keystore with the following command. This assumes the certificate is stored in a file called GIAG2.cer

    keytool -import -trustcacerts -file GIAG2.cer -alias giag2 -keystore GIAG2.jks -storepass secret -storetype JKS

15. In the left menu of the iWay Service Manager console, click Security Providers, and then click New to create a new Keystore provider to be used as the truststore.

    The following table lists the parameters and values of the Keystore provider.

    Parameter	Value
    Name	giag2
    Description	Google Internet Authority G2
    Keystore	Path to GIAG2.jks
    Keystore Password	secret
    Keystore type	JKS
    KeyStore JCE Provider	SUN

16. Click New again to create another Keystore provider for the private key of the service account.

    Parameter	Description
    Name	cloudkey
    Keystore	Path to the keystore containing the service account private key.
    Keystore Password	The keystore password chosen by Google, for example, notasecret.
    Keystore type	PKCS12-DEF
    KeyStore JCE Provider	BC

17. Create an SSLContext provider to be used by the HTTPS connections, and accept all default parameters except the following:

    Parameter	Description
    Name	GoogleSSL
    Keystore Provider	Not used but required. You can enter giag2
    Truststore Provider	giag2
    Security Protocol	TLS

18. Create an HTTP Client provider to manage connections to the Google Cloud Storage by clicking Pooling Providers in the left menu of the iWay Service Manager console, and then clicking New.
19. Accept all default parameters except those found in the following table:

    Parameter	Description
    Name	GoogleClient
    SSL Context Provider	GoogleSSL

20. In your process flow, create an instance of the OAuth 2.0 Authentication Service configured as shown in the following table. Replace the values in angle brackets with the actual value obtained in the Google Developers console.

    Parameter	Description
    HTTP Client Provider	GoogleClient
    Destination URL	URL of the object in the Google Cloud Storage.
    HTTP Method	GET
    Scopes	https://www.googleapis.com/auth/devstorage.read_only
    Project ID	The Google Project ID.
    Service Account Email	The service account email address chosen by Google.
    KeyStore Provider	cloudkey
    Private Key Alias	privatekey
    Private Key Password	Password chosen by google, for example, notasecret.

    The Destination URL can take one of the following forms:

    • https://<bucketname>.storage.googleapis.com/<objectname>
    • https://storage.googleapis.com/<bucketname>/<objectname>

    For example, if the bucket name is mybucket-example-com, and the object name is root.xml, the destination URL can be one of two equivalent URLs:

    • https://mybucket-example-com.storage.googleapis.com/root.xml
    • https://storage.googleapis.com/mybucket-example-com/root.xml

    This instance of the OAuth 2.0 Authentication Service accepts any input document since the GET method does not send a request entity in the body of the message. The output document will be the contents of the object found in the Google Cloud Storage or an error document.