TABLE OF CONTENTS
- Article Content
- Creating a Key
- Key Types
- Referencing a Key in a Processor
- Exposing Keys via API
The scope of the Credentials functionality is to allow the user to get access to secure data on an external data resource without explicit authentication at the time the data is requested.
In the credentials tab, all the existing keys will be listed in a descending order of modification time. Within the credentials overview, the user will see details like key name, the type of the key, connection name (if a key is referenced in a connection), the permissions he has, etc.
A user with full rights will be able to create, delete, edit and share the keys to different projects.
Please be mindful that user with respective rights may be able to access these credentials as well! So always make sure, especially if personal credentials are used, that user rights are set properly and accordingly.
Creating a Key
- First of all, navigate to the "Credentials" tab in ONE DATA.
- Within the tab click on 'Create' from the left sidebar.
- A new window pops up and the 'Basic Auth' key type is selected by default.
- Fill in the mandatory information for the respective key type.
- Click on "Create". A new key is created and is now populated on top of the list in the credentials tab.
Important things to note when creating credentials:
- There are no restrictions for the password.
- Once a key is saved, the key type cannot be edited.
- A key cannot be deleted, unless the connections currently using the key are deleted.
This section will explain the different key types for credentials.
This is the type for any basic authentication with a username and a password.
|Key name||Name of the your key.|
|Username||The username that you want to authenticate with.|
|Password||The respective password for the given user.|
These are the key types for the authentication for certain platforms.
ONE DATA Auth
The ONE DATA authentication type is very useful when working with the ONE DATA API inside of your workflows.
With this credential type and the respective connection, you can authenticate requests by using the account information of a ONE DATA user.
Without these credentials you would need to save your JWT within a REST API Processor. This is problematic because authentication tokens can expire, which means you would need to update the workflow every time the token becomes invalid.
|Key name||Name of the your key.|
|Username||Name of the ONE DATA user.|
|Password||Password of the ONE DATA user.|
|Authentication Endpoint URL||The URL of the endpoint the authentication request can be sent to, to obtain the access token in the authorization HTTP header.|
Usually this is the URL to the ONE DATA instance followed by the API path for login: "[instance_URL]/api/v1/users/login"
It has the following required fields:
|Key name||Name of the your key.|
|Client Id||Your Personio client id.|
|Client Secret||The Personio client secret.|
|URL||The URL the authentication request is sent to. (https://api.personio.de/v1/auth). |
Microsoft ROPC (Resource Owner Password Credentials)
This is the key type for the authentication for Microsoft Services, for example the MS Graph API.
To be able to use this key type, you need to register ONE DATA / your Workflow via Microsoft Azure. If you already have an app registered, you can skip this part.
Register an application in MS Azure:
- First, you need to click "New Registration" on the upper left of the part. In the appearing dialog, select a name and then an account type that fits your needs.
- After that, you will be redirected to the configuration menu of the app. There you can see your "ClientId" (Application Id) and "TenantId" (Directory Id) in the center of the page.
- Under the "Authentication" tab in the side bar, you need to set the application to public, to be able to use ROPC.
- Under "Certificates & Secrets" you can generate your Client Secret.
- The last important point to mention is, that under "API Permissions" you can configure which information should be accessible via the registered application.
These are the required fields in ONE DATA to create credentials for MS ROPC:
|Key name||Name of the key.|
|Client Id||The Application (client) Id the the Azure portal assigned to your app|
|Tenant||The directory tenant you want to log the user into. This can be in GUID or friendly name format|
|Username||The user's email address (any valid Microsoft account holder).|
|Password||The user's password|
|Client Secret||This parameter is optional. |
If your app is a public client, then the client_secret cannot be included.
If the app is a confidential client, then it must be included.
Referencing a Key in a Processor
Similarly, within the Flexible REST API processor, under the 'AUTHENTICATION' section, the user can override the key provided by the Connection by selecting another key.
Exposing Keys via API
Since ONE DATA version 74 (Server 48.0.0, Client 1.200.0) Credential Keys are now exposable. This means that their information (username, password, etc) can now be retrieved via API and used in Functions and Python Processors without having to write them in plaintext. Formerly, Keys were only used in OD's internal data processing, e.g. Workflows and Connections. The user was actually given no direct possibility to retrieve the plaintext Credentials after creating or editing one.
If the owner of a Credential decides to un-expose a Key, please be aware that any Function or Processor that requests and uses these Credentials will most likely fail during future executions.
To expose or unnexpose a Credentials, you have to be the owner of the Credential. Any user with WRITE access can still change the underlying information (e.g. username and password), but is not able to expose or un-expose the Key.
Please also note that this has some security implications that should be considered. Any user with READ access to your exposed Credential will be able to see its plaintext.
How To Expose a Key
By default, all Credentials are un-exposed. When creating or editing a Credential, set it as exposed by ticking the checkbox "Expose Key".
An exposed Key is indicated in the Credentials list by a checkmark in the "Exposed" column.
How To Use an Exposed Key
The button beside the checkbox in the creation/edit dialog reveals an information box. It shows code snippets for using the exposed Key in Python Processors, Functions or locally (curl).
If the Key has not yet been created, there is a placeholder for its ID inside the code. When editing an existing Key, its ID has been entered. The code snippets can just be copied and used as is or adapted to your specific use case.
Another way to get the Key ID for the snippets is to go to the Credentials list and perform the action "Copy Key ID to clipboard".
The provided code snippets get and then print the Credentials. As an example, the Python code was run using a Function and shows the Key's properties as follows. The result will be the same for the other two options, just shown in a Processor or locally.
When using an unexposed Key, a message that the ID is not exposed is returned. The example snippets print this message. If the code had used the returned Credentials in some way, the Function would have failed since there is no returned "keyInformation".