We're Moving ... Again
Yes, the Identity Cloud documentation is once more on the move. And this time we're headed to two different locations:
The REST API documentation is moving to here: https://developer.akamai.com/api/
And the remainder of the documentation is moving to here: https://learn.akamai.com/en-us/webhelp/identity-cloud/technical-library/GUID-76D7D02B-8C6F-4188-AF17-0711F9620B38.html
As for the Education Center, well, the Center itself will disappear on July 23rd. We apologize for any inconvenience, but we look forward to becoming a full-fledged member of the Akamai family.
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.
Note. 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 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.
Note. 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.
In Manage Properties, click Create Property.
Enter the property's name.
Go to Permissions and select the features for the property (used to manage access to user profiles and application management capabilities). A description of the available permissions (referred to as “features” in the API documentation) can be found at this page.
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 Janrian user profile attribute, you cannot modify that attribute unless your write 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 and Mobile SDKs were 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.
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.
The set an access schema, you use the entity type endpoint entityType.setAccessSchema. Some things to consider when working with access schemas:
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.
Important: Pass in the list of attributes to which you want to give access tos. 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.
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 "whitelist" for a target client, overwriting the previous whitelist. (A whitelist 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 whitelist for itself, the whitelist 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 whitelist. 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 whitelist of ["0.0.0.0/0"], which means that you can access the client from any IP address.