Guide
TrainingSupportCommunity

JavaScript SDK best practices

Suggest Edits

📘

It's highly-recommended that you contact Akamai support (or your Identity Cloud representative) before you change the client secret for an owner client. That's because changing an owner client secret can have repercussions that go beyond simply assigning a new secret to the client. Note that this is especially true for organizations running Hosted Login. See Contact support if you need to change an owner client secret for more information.

The goal for any secure application is to minimize the exposure and access to the minimal functionality required for the application to function: if an application only needs to be able to read user profile data, then that application should not have the right to create, modify, or delete user profile data. Elevated access or privileges (i.e., more privileges and permissions than you really need) might be easier to implement, but that often leaves an application exposed to vulnerabilities or unauthorized data access.

The following recommendations are intended to help Akamai customers ensure that they have configured their applications with the minimal levels of access to help ensure the security of their customer data.


API Call Considerations

Akamai's RESTful API supports both POST and GET methods, but. for security reasons, POST should be used when retrieving information. The use of GET methods or appending Query Parameters to the URL as part of a POST method may expose Client Secrets unnecessarily.

📘

Using the POST method does not apply to the Configuration APIs or to the Clients and Settings APIs. When working with those APIs, you should use the GET method when retrieving data.


API Clients

API Clients are used with the RESTful APIs to grant only the access needed to different sets of credentials. When your Identity Cloud is first set up, your Akamai representative will create an API Client with minimal read-only (login_client) data access to user data. This API Client is used for building code to retrieve user data securely without having to use the owner API Client.

📘

However, the login_client is restricting to working with data for the logged-in user only. For example, you cannot use login_client to retrieve data for multiple users with a single API call, nor can you authenticate as user Bob and then retrieve user profile data for user Mary.

All Registration implementations begin with:

  • An Owner API Client. Available to access all API endpoints. Should only be used for configuration purposes, such as provisioning API Clients.

  • A Login Client. Access restricted to sign in and registrations based API endpoints. Used solely for the code that authenticates visiting users.

Depending on other code used when integrating the Registration solution, more API Clients may be needed. The best practice is to create an API Client for a specific purpose, giving it only the permissions needed for the assigned task.

  • Example 1. Create similar API Clients for each of your developers and partners. This allows the customer to restrict partners to specific attributes.

  • Example 2. Use a read-only “login_client” API Client for the Identity Cloud Registration system, and use a separate “direct_access” API Client for any server-to-server API calls that you may need to make between your web server and the REST APIs.

You may wish to further restrict the functionality of some of the API calls. For example, you may want to allow certain vendors, or internal groups, access to your website to modify their information, but you might want to limit their access to a specified set of attributes (for example, they can modify a user's phone number or street address, but cannot modify their email address). You can do this on a per-API Client basis by creating and configuring access schemas.

To create a new API client in the Console, complete the following procedure:

  1. In Manage Properties, click Create Property.

  2. Enter the property's name.

  3. Go to Permissions and select the features for the property (used to manage access to user profiles and application management capabilities). See API clients and permissions for a description of the available permissions (referred to as “features” in the API documentation).

  4. Click Create Property. The new client ID and secret will be available in Settings.

To create the new API client via API, use the /clients endpoint. And to restrict the fields that can be accessed, use the setAccessSchema API call.

Note that clients with the direct_read_access and direct_access features are still subject to the access schemas. For example, if the client has a write access schema defined, they will only be able to write to an attribute if that attribute exists in the access schema assigned to them. Although email is a valid Identity Cloud user profile attribute, you cannot modify that attribute unless your access schema gives you permission to do so.

Note, too, that the direct_access feature implies the direct_read_access feature.


API Client Secrets

One of the most important things to remember is this: always keep your API Client Secrets secure! The client secret for an API client is the password to your Registration database. Akamai will never require or request your API Client Secret, and you should never email, post in a support ticket, post to a public website, store in a hosted code repository, or transfer an API Client Secret. If you must send the information of an unsecured channel, Akamai recommends using an encryption tool such as PGP to encrypt the data before sending it.

Akamai monitors our systems for potentially-compromised API Client accounts. If Akamai finds a compromised API Client, we will be forced to change the API Client Secret on that API Client and notify you of the change.

Akamai's web-based Registration solution was designed to never require the inclusion of API Client secrets in the website or native application code. Customers should never include API Client secrets in any end user-viewable website code or in compiled native applications.


Permissions

You can set several different permissions, such as direct_access and access_issuer, through the Console. See the discussion of these permissions in the API Clients area above.

To set an access schema, you use the entity type endpoint entityType.setAccessSchema. Some things to consider when working with access schemas:

  • Access schemas only apply to API-based implementations of the Identity Cloud. If you are using a JavaScript SDK-based implementation then access to forms ands fields is managed by the flow.

  • You need to use your main (Application Owner) client ID and secret for the entityType.setAccessSchema API call.

  • The default entity type is user. Each entity type within a Registration Schema can have unique access schemas per API Client. Custom access schemas must be applied for each API Client and entity type. There is no inheritance of access schemas.

  • Set access_type to read to set the read permissions, or write to set the write permissions.

Pass in the list of attributes to which you want to give access to. For example, if you only want to allow the API clients to read the email, name, and birthday attributes, you might pass in something like this:

[email, displayName, birthday]

You must make this API call once each for read and write permissions; that's because by default, each client ID comes with full read and write privileges. In other words, if you only make the API call to set read permissions, then the client will have limited permissions for reading the data, but full permissions for writing the data.


Use /clients/set_whitelist

It is possible to restrict a specific API Client to a specific TCP/IP address or series of addresses; this can be done by changing the IP allow list for a target client, overwriting the previous list. (An allow list specifies the IP addresses which are allowed to access an API client.)

Only the owner client may make this API call. If the owner client sets the allow list for itself, the list must allow access from the IP address making the call. For example, if you try to make the API call from computer 192.168.1.1, then 192.168.1.1 must be included on the new allow list. If it is not, the API call will fail. (Which is good: if it didn't, then as soon as the API call completed computer 192.168.1.1 would no longer have access to the API client.)

All new clients start off with a default allow list of ["0.0.0.0/0"], which means that you can access the client from any IP address.

Console Considerations

The Console is ideally suited for management and completion of administrative tasks and actions. Many levels of access are available.

Updated about 1 year ago