Quick start: Liberty for Java backend apps

Video tutorial

Check out the following video to see how you can use App ID to protect a simple Liberty for Java application. All the information that is covered in the video can also be found in written form on this page.

Don't have an app that you can try out the flow with? No problem! App ID provides a simple Liberty for Java sample app.

Before you begin

Before you get started with App ID in your Liberty for Java back-end application, you must have the following prerequisites:

• An instance of the App ID service
• The IBM Cloud CLI
• Apache Maven 3.5+
• Java 8+

Obtain your credentials

You can obtain your credentials in one of two ways.

• By navigating to the Applications tab of the App ID dashboard. If you don't already have one, you can click Add application to create a new one.

• By making a POST request to the /management/v4/<tenantID>/applications endpoint.

  Request format:
  ```sh {: codeblock}
  curl -X POST \  https://us-south.appid.cloud.ibm.com/management/v4/<tenantID>/applications/ \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <IAMToken>' \
  -d '{"name": "ApplicationName"}'
  ```
  Example response:
  ```json {: screen}
  {
    "clientId": "xxxxx-34a4-4c5e-b34d-d12cc811c86d",
    "tenantId": "xxxxx-9b1f-433e-9d46-0a5521f2b1c4",
    "secret": "ZDk5YWZkYmYt*******",
    "name": "app1",
    "oAuthServerUrl": "https://us-south.appid.cloud.ibm.com/oauth/v4/xxxxx-9b1f-433e-9d46-0a5521f2b1c4",
    "profilesUrl": "https://us-south.appid.cloud.ibm.com",
    "discoveryEndpoint": "https://us-south.appid.cloud.ibm.com/oauth/v4/xxxxxx-9b1f-433e-9d46-0a5521f2b1c4/.well-known/openid-configuration"
  }
  ```
  

Configure your server.xml file

1. Open your server.xml file.

2. Add the following features to the featureManager section. Some features might come built in with Liberty. If you receive an error when you run your server, you can install them by running .installUtility install {name_of_server} from the bin directory of your Liberty installation.

   <featureManager>
      <feature>appSecurity-2.0</feature>
      <feature>openidConnectClient-1.0</feature>
      <feature>ssl-1.0</feature>
      <feature>servlet-3.1</feature>
   </featureManager>
   

3. Configure SSL by adding the following to your server.xml file.

   <keyStore id="defaultKeyStore" password="{password}"/>
   <keyStore id="RootCA" password="{password}" location="${server.config.dir}/resources/security/{myTrustStore}"/>
   <ssl id="{sslID}" keyStoreRef="defaultKeyStore" trustStoreRef="{truststore-ref}"/>
   

4. Create an Open ID Connect Client feature and define the following placeholders. With the credentials that you obtained, fill the placeholders.

   <openidConnectClient 
      id="oidc-client-simple-liberty-backend-app" 		
      inboundPropagation="required"
      jwkEndpointUrl="<region>.appid.cloud.ibm.com/oauth/v4/<tenantID>/publickeys"
      issuerIdentifier="<region>.appid.cloud.ibm.com/oauth/v4/<tenantID>"
      signatureAlgorithm="RS256"
      audiences="{client-id}"
      sslRef="oidcClientSSL"
   /> 	
   

   OIDC element variables for Liberty for Java apps

   Variable	Description
   id	The name of your application.
   inboundPropagation	To propagate the information received in the token, the value must be set to "required".
   jwkEndpointUrl	The endpoint that is used to obtain keys in to validate the token. Learn more about the available regions. You can find your tenant ID in the credentials that you previously created.
   issuerIdentifier	The issuer identifier defines your authorization server. Learn more about the available regions. You can find your tenant ID in the credentials that you previously created.
   signatureAlgorithm	Specified as "RS256".
   audiences	By default, the token is issued for your App ID client ID that can be found in your application credentials.
   sslRef	The name of the SSL configuration that you want to use.

5. Define your special subject type as ALL_AUTHENTICATED_USERS.

   <application 
      id="simple-liberty-backend-app" 
      location="location-of-your-war-file" 
      name="simple-liberty-backend-app" 
      type="war">
   
      <application-bnd>
         <security-role name="myrole">
               <special-subject type="ALL_AUTHENTICATED_USERS"/>
         </security-role>
      </application-bnd>
   </application>
   

Configure your web.xml file

In your web.xml file, define the areas of your application that you want to secure.

1. Define a security role. This role must be the same role that you defined in the server.xml file.

   <security-role>
   <role-name>myrole</role-name>
   </security-role>
   

2. Define a security constraint.

   <security-constraint>
      <display-name>Security Constraints</display-name>
      <web-resource-collection>
         <web-resource-name>ProtectedArea</web-resource-name>
         <url-pattern>/api/*</url-pattern>
      </web-resource-collection>
      <auth-constraint>
         <role-name>myrole</role-name>
      </auth-constraint>
      <user-data-constraint>
         <transport-guarantee>NONE</transport-guarantee>
      </user-data-constraint>
   </security-constraint>
   

Test your configuration

Now that you finished the initial installation, build the app and test your configuration to ensure that everything is working as expected.

1. Change into your application directory.

2. Build your application.

   server run
   

3. Make a request to the protected endpoint. An error is returned.

4. Obtain an access token.

5. With the access token that you obtained in the previous step, make a request to the endpoint. You are now be able to access the protected endpoint. Verify that the response contains what you expect.

Next steps

Ready to start perfecting your authentication experience? Try walking through this blog or learning more about app-to-app communication.