Using a Service Account with the Flexera One API

[#1]

Introduction: Use the following steps to create a service account for an application that will connect to Flexera One’s APIs. Service accounts are complimentary to refresh tokens. They can be given lesser privileges and can be decoupled from any specific user. Create a distinct service account for each application you wish to connect to Flexera One. Please note that the domain for any endpoints used needs to match the region where your org is hosted.

NAM: .com
EMEA: .eu
APAC: .au

Instructions:

1. Get a refresh token from the Flexera One UI.
2. Use the refresh token to get an access token. Store this token in a variable called USER_TOKEN.
3. Identify the organization that the service account will exist in and save this number in a variable ORG_ID.
4. Create a service account. Use a name appropriate for the application which will use the service account. Optionally, provide a description to describe the use of the service account. Notice the service account’s ID is returned (2263), keep this ID at hand.

   curl -s https://api.flexera.com/iam/v1/orgs/$ORG_ID/service-accounts \     
    -H "Authorization: Bearer $USER_TOKEN" \   
   -d '{"name": "my application", "description": "Reads data from Flexera One APIs"}' -i
   
   HTTP/2 201 
   ...
   location: /iam/v1/orgs/1105/service-accounts/2263
   ...

5. Show the service account.

   curl -s https://api.flexera.com/iam/v1/orgs/$ORG_ID/service-accounts/2263 \
    -H "Authorization: Bearer $USER_TOKEN" | jq
   
   {
     "id": 2263,
     "name": "my application",
     "description": "Reads data from Flexera One APIs",
     "createdBy": 121456,
     "createdAt": "2023-07-10T20:28:48.531479Z",
     "updatedAt": "2023-07-10T20:28:48.531479Z",
     "kind": "iam#service-account",
     "ref": "iam#service-account:2263"
   }​

6. Assign role(s) to the service account. The service account should be given the least permission possible to accomplish its tasks.
7. Review the roles in the organization.

   curl -s https://api.flexera.com/iam/v1/orgs/$ORG_ID/roles \                
    -H "Authorization: Bearer $USER_TOKEN" | jq
   
    [
    ...
    {
       "id": 678907,
       "createdAt": "2020-03-20T16:18:56.542732Z",
       "name": "iam_admin",
       "capability": "iam",
       "privileges": [
         ...
         "iam:user:index",
         "iam:user:show"
       ],
       "kind": "iam#role"
     },
    ...
    ]​

8. Identify the name of the role that should be granted (iam_admin will be used for this demonstration). See Flexera One Roles for more details on roles.
9. Grant the role(s) to the service account. Notice the service account API returned an older ref format (iam#service-account:2263), but we use the newer ref format (ref::::iam:service-account:2263) in this API call. See resource references for more detail.

   curl -s https://api.flexera.com/iam/v1/orgs/$ORG_ID/access-rules/grant -X PUT -i \
    -H "Authorization: Bearer $USER_TOKEN" -d '{
     "role": {
       "name": "iam_admin"
     },
     "subject": {
       "ref": "ref::::iam:service-account:2263"  
     }
   }'
   
   HTTP/2 204 
   ...

10.  Repeat this step for any number of roles which must be granted to the service account.
11. Create a client for the service account. The client contains the service account's credentials.

    curl -s https://api.flexera.com/iam/v1/orgs/$ORG_ID/service-accounts/2263/clients \
     -H "Authorization: Bearer $USER_TOKEN" -X POST
    
    {"clientId":"<clientId>","clientSecret":"<clientSecret>","createdBy":121456,"createdAt":"2023-07-10T20:50:41.195629Z","kind":"iam#service-account-client"}

12. The clientId and clientSecret must be stored securely, as they are sensitive. Anyone with access to these credentials will have access to your organization. In the next step, the application will need to use the clientID and clientSecret. Those values should be securely loaded into the application, or stored in a place where the application can securely access them.
13. Run the application. The remaining API calls are performed by the application, not the user setting up the service account. However, for this demonstration, we will perform them with curl.
14. Get an access token. The access token is a temporary credential (see from the response that the access token expires in 3600 seconds or 1 hour). See Flexera One API Authentication for details.

    curl -X POST https://login.flexera.com/oidc/token -d \
    "client_id=<clientId>&client_secret=<clientSecret>&grant_type=client_credentials" | jq
    
    {
      "access_token": "<accessToken>",
      "expires_in": 3600,
      "token_type": "Bearer"
    }

15. Use the access token to call Flexera One APIs. In this example, we list the users in the org, which is permitted for the role we granted our service account (iam_admin).

    curl -s https://api.flexera.com/iam/v1/orgs/$ORG_ID/users \
     -H "Authorization: Bearer $ACCESS_TOKEN" | jq .
    
    {
      "values": [
        {
          "kind": "iam#user",
          "ref": "iam#user:111222333",
          "id": 111222333,
          "email": "JDoe@flexera.com",
          "firstName": "Jane",
          "lastName": "Doe",
          "createdAt": "2022-11-14T15:29:45.191995Z",
          "updatedAt": "2023-06-28T20:40:14.999786Z",
          "lastUILogin": "2023-06-28T20:40:15.705245Z",
          "lastAPILogin": "2023-01-23T19:51:56.346877Z"
        },
        ...
        ]
    }​

16. After the access token is expired (or is nearing expiry), repeat the previous /oidc/token API call (step 14) to get a new access token. The access token is a sensitive credential, so the application should not expose the value to be read by any user.
17. The application can continue using the access token to accomplish its tasks, replacing its token whenever necessary.

More Details: You will need to use the api.flexera endpoint that matches the environment that your org is located in (NAM=.com, EMEA=.eu, and APAC=.au). Please note that the ITAM Data API does not support the use of service accounts at this time.

[ryanhardcastle0]

Remember to edit the uri api.flexera.com to whatever geographic instance you're using e.g. api.flexera.eu / api.flexera.au

Otherwise you'll get an 401 unauthorized error.