The capabilities described on this page are included in Appian's standard capability tier. Usage limits may apply. |
A service account is a special type of user account in Appian that is a member of the Service Account system group. They are used in portals to authenticate back to Appian. This allows portal users to access information and processes in Appian without having to log in. Using service accounts in this way keeps your Appian environment secure while ensuring your portal users have access to the information and processes that are important to them.
You need to give service accounts the appropriate permissions to act on behalf of the portal. See Required permissions for portal service accounts for what permissions to grant depending on the portal use case.
The page provides information about using service accounts in portals.
Only system administrators can create service accounts. There are a few different options for creating service accounts:
The permissions you give your service account will depend on the use cases for your portal. This table outlines the appropriate permissions to give to the service account based on what your portal does. For step-by-step instructions on setting up a portal service account with the appropriate permissions, see Create a Portal.
You don't need to give access to every object used in your portal. Only the objects listed below.
If your portal… | Grant the following permissions… |
---|---|
Queries records | Viewer permission to the record type. Be sure to configure any necessary record-level security as well to determine who can see which records. |
Adds, updates, or deletes records | Viewer permission to the record type. Be sure to configure any necessary record-level security as well to determine who can see which records. Initiator permissions to the process model. See Start Process Smart Service for more information on the difference between Initiator and Viewer permissions. |
Starts a process | Initiator or Viewer permissions to the process model, along with any other permissions required for the smart services used in the process model. See each smart service page for the permissions needed. If the portal needs access to process model properties, process instance properties, or process variable values, give the service account Viewer permissions. See Start Process Smart Service for more information on permissions needed. |
Uploads documents | Editor permissions to the document folders that files will be uploaded to. |
Displays or downloads documents | Viewer permissions to the document folders where the documents are stored. |
Queries or writes data to a publicly-accessible external database | Viewer permissions to the data store for the external database. |
Queries or writes data using a CDT | Grant the service account that is tied to the API key Viewer permissions to the web API and data store. |
Uses a custom integration to use partially compatible capabilities | Grant the service account that is tied to the API key Viewer permissions to the web API and any other design object that the portal needs access to. |
Uses a connected system plug-in with an associated component plug-in | Viewer permissions to the connected system. |
Using service accounts prevents you from unintentionally exposing the wrong data or documents in a portal. As such, we recommend that you only grant the service accounts permissions to the records, documents, and processes that are needed for the portal.
As a best practice, avoid setting Default (All Other Users) to have Viewer permission on your record types. Service accounts are considered "users" for this setting, which means that this grants viewer access to all service accounts as well as all logged-in users.
You can view and update the record type permissions that the service account can currently access directly from the portal object. Use the View record type permissions for the service account link in the Service Access section to make sure the portal service account:
To add permissions to a record type that is not in this list, go to the security settings for the record type.
That being said, portals will only expose data or start processes that are directly called in an interface. Even if the service account has permission to other record types or processes, if the developer does not directly call the record type or process in the portal, they will not be accessible from the portal.
If one or more of the following scenarios applies to a portal, the portal object must have a service account configured in the Service Access section:
** Ensure the service account has the required permissions to view data and perform actions for the portal.
Before you deploy a portal to different environments, create the service account in each environment with the same username and group membership. To learn more, see deploying a portal.
Service accounts can be used for two different types of permissions in a portal:
If your portal uses web APIs, you can use the same service account for portal and web API permissions, but you don't have to.
If necessary, you can rotate the keys that your portal uses. This section outlines how to rotate API keys used for your portal service account, as well as the other keys your portal may use.
When you add a service account to a portal, an API key is automatically generated when the portal is published. You can see this API key in the Web API Authentication page in the Admin Console.
If necessary, system administrators can rotate this API key to invalidate the old one and create a new one.
Note: After you delete the old API key, end users may encounter errors until the portal is republished. Therefore, when rotating API keys in production environments, we recommend waiting for off-peak hours.
To rotate a portal service account API key:
Delete the API key by clicking the red X.
Your portal may use other types of keys that require a different method to rotate.
If a portal uses Web APIs, you can rotate the API key used for the web API by performing the following:
Open a support case to rotate either of the following keys:
Service Accounts in Portals