Service Principal Management
What is a Service Principal Account?
A Service Principal Account is a non-interactive machine identity used for automated system-to-system connections to DataHive. Unlike interactive user accounts, service principals use client credential flow with longer-lived tokens, making them suitable for automated pipelines and integrations.
See the System Connection guide for help choosing the right connection type.
What types of connections can a Service Principal Account have?
| Type | Purpose |
|---|---|
| Data Request Connection | Lets your system download data from approved Data Requests. |
| Tenant Connection | Lets your system upload files to datasets under a specific Tenant. |
You can only add additional connections of the same type to an existing Service Principal Account. If you require a different connection type, you must request a new Service Principal Account.
How do I create a Service Principal Account?
- Go to the "Requests" page and select the "Service Principal" tab.
- Fill in the account creation form with your team details, connection type, and public key.
- Submit the request for Platform Admin approval.
See Account Creation for the full guide.
What permissions can team members have on a Service Principal Account?
| Permission | Description |
|---|---|
| Read-Only | The user can only view the details of the service principal account. |
| Manage | The user can view and make changes to the service principal account (e.g. change IP address, public key, request more connections). |
What is the approval workflow?
The approval process depends on the connection type:
- Data Request Connection: Platform Admin approves the account, then the Data Request Owner approves the connection.
- Tenant Connection: Platform Admin approves the account, then the Tenant Manager approves the connection, then the Tenant Admin assigns specific datasets.
See Approval Workflow for details.
How do I add more connections to an existing account?
- Data Request Connections: Enter the fulfilled data request ID in the connection form. The data request owner will be notified to review and approve.
- Tenant Connections: Select the tenant name from the dropdown. The Tenant Manager will be notified to review and approve.
See Adding more system connections.
How do I generate the required keypair?
A keypair is required for authentication. Only the public key is sent to DataHive.
Generate private key:
openssl genrsa -aes256 -passout pass:<YourPassphraseHere> -out rsa_key.p8 2048
Generate public key:
openssl rsa -in rsa_key.p8 -pubout -out rsa_key.pub -passin pass:<YourPassphraseHere>
See Account Creation for the full guide.
How do I rotate my keys?
Keys expire after 1 year from the time of creation.
- Go to the service principal detail page and expand "Service Principal Details" to view the key expiry date.
- Click "Edit details" to update the public key.
- You can provide 2 public keys simultaneously to facilitate a smooth key rotation.
Note: Public keys cannot be reused.
See Key Rotation.
How do I change the IP address for my account?
You can update the whitelisted IP address from the service principal detail page. Supported formats:
- Individual address (e.g.
10.0.0.1) - Range of addresses (e.g.
10.0.0.0-10.0.0.255) - CIDR block (e.g.
10.0.0.0/24)
Restrictions:
- Intranet IPs: maximum 256 IPs, must be in
10.x.x.xformat (GEN routable). - Internet IPs: maximum 32 IPs, must be of Singapore origin.
See Change IP Address.
Can a Service Principal Account hold both Data Request and Tenant connections?
No. A single Service Principal Account can only hold one type of connection - either Data Request connections or Tenant connections, not both. However, one account can hold multiple connections of the same type (e.g. multiple Data Request connections). If you need both connection types, you must create separate Service Principal Accounts for each.
Can a Service Principal Account publish datasets?
No. Service Principal Accounts can only upload files. A Tenant Admin must publish the dataset after the upload completes.