Developer Portal
The following explains the functionality of the Identity Service Developer portal. The tools in this portal allow you to set up and manage integrations with parter applications.
Tenants
Upon first entering the Developer Portal, you will see a list of all tenants that you own (including those you share ownership of). Clicking on one will bring up all the management controls for that tenant, detailed throughout the rest of this page.
To create a new Tenant, you can either create your own by manually entering the necessary information, or automatically board a tenant from an supported partner application. You can do this simply by entering the URL of the application you wish to board, and we'll take care of the rest.
Creating a tenant manually, or editing an existing tenant, will give you the following settings:
| Setting | Description |
|---|---|
Display Name | This is the "friendly" name of the tenant. This will be used as the name users see as they log in, and will be used in all email correspondences. |
Name | A unique indentifier for this tenant - think of it as the tenant's username. It is used by IDS to identify this tenant, and will also be part of the URL users will see as they log in. Once the Tenant is created, this cannot be changed. It can only contain lowercase letters, numbers, underscores, and dashes. |
Theme | Select one of the provided themes to use for this tenant. One should have been created for your product, if not, contact us or use one of the others. The "Default" theme is Vanco-branded. The theme will determine the look and feel of all IDS pages and emails. |
Logo | A URL to a logo image to use on the login page. |
Users Sign In With | IDS supports logging in users using any combination of usernames, emails, or phone numbers. Unless your application currently uses usernames to log in, we recommend not turning on username sign-in and instead using email. Sign in with email must be enabled in order to turn on social auth providers. |
Password Format | Select the password hashing format currently in use in your application. |
Auth Providers | Available for open tenants with email sign-on enabled. If you would like, pick from the list of supported auth providers. These will be presented to users on the login screen as an alternate method of signing in. Users can either connect their social auth account to an existing account in this tenant, or can use it to create a new account. |
For details on using our Tenants API, click here.
Apps
Here you can see a list of applications in this tenant, edit them, or create new applications.
Creating or editing an application will give you the following settings:
| Setting | Description |
|---|---|
Name | Can only be set during initial app creation. A unique indentifier for this application - think of it as the application's username. It is used by IDS to identify this application. It can only contain lowercase letters, numbers, underscores, and dashes. |
Homepage URL | The default landing page of your application you want users to be directed to. |
Redirect URLs | A whitelist of one or more URLs for IDS to use for authorization callbacks. |
Redirect Logout URLs | A whitelist of one or more URLs for IDS to redirect users to after logging out. |
Application Type | Can only be set during initial app creation. Choose the option that best describes your application. More details here. |
Enable Registration | Turns on the ability for users to register new accounts from the login page. |
Allow unregistered users to sign in | Allows users to be able to sign in to this application without having completed the process of creating their account. Can only be enabled if the parent tenant allows sign-in via email only. This setting only makes sense for very specific scenarios; for most applications this setting should be left off. |
For details on using our Applications API, click here.
Webhooks
The webhooks tab has the tools necessary for you to set up subscriptions to important IDS events via webhooks. Clicking on the tab will show you a list of webhook subscriptions currently set up, if any.
Properties
When creating or editing a webhook subscription, you will be presented with the following settings (with slight variations depending on whether you're creating or editing):
| Setting | Description |
|---|---|
URL | A absolute URL to the API endpoint in your application that will consume POST messages from this webhook. |
Secret Token | An arbitrary private key that IDS will use to sign the event payload via a HMAC. This can be anything you like. Note that you will also need to use it in the above endpoint to verify the HMAC header included in the POST. If you change this, make sure to change it in your code as well. |
Enabled | Defaults to enabled for new webhooks. Allows you to turn webhook subscriptions on and off as desired. |
Event Subscriptions | The events you want this webhook to send to the above endpoint. You could send multiple events to a single function and decide what to do with them there, or you could set up separate functions to handle individual events. |
Events and payloads
Each webhook will make a POST to the URL you specify. The post will have a request header ("X-Webhook-Signature") with the HMAC hash of the payload, computed using the secret key you specify. It is your responsibility to re-hash the payload on your side and compare the two so as to verify the authenticy and integrity of the data payload.
In addition to the properties specific to each event type, there are a few properties included in every webhook post that describe the event itself, that may be useful to you:
| Property | Description |
|---|---|
EventId | (Guid) A unique GUID for this message |
Timestamp | (Date) A dateTimeOffset of the time the message was sent (e.g. "2019-06-19T08:00:00-06:00") |
Event | (String) The period-delimited code for the event type (e.g. "account.profile_updated") |
Tenant | (String) |
###Profile Updated account.profile_updated
This event fires every time a user updates their profile information, and gives you a snapshot of the latest data for that user.
| Property | Description |
|---|---|
UserId | (Guid) The ID of the updated user account |
FamilyName | (String) |
GivenName | (String) |
PhoneNumber | (String) |
AddressA | (String) |
AddressB | (String) |
StateOrProvince | (String) |
Country | (String) |
City | (String) |
PostalCode | (String) |
Email | (String) |
###Email Updated account.email_updated
This event fires every time a user updates their email address.
| Property | Description |
|---|---|
UserId | (Guid) The ID of the updated user account |
Email | (String) The user's updated email address |
###Account Inactivated account.inactivated
This event fires every time a user account is inactivated due to inactivity.
| Property | Description |
|---|---|
UserId | (Guid) The ID of the inactivated user account |
Sharing
Here you can add and remove other Vanco employees as owners for a tenant. Being an owner means they can now see this tenant in their list of tenants and have the same ability to manage it as you do. So be careful sharing production data with anyone unless needed, but also be cognizant of the logistical issues that can arise from only one person being able to manage a tenant.