Integrations
Connect Duende IdentityServer
Connect Duende IdentityServer as an Authorization Server in Apiable. Enter the Authority URL, DCR endpoint and registration credentials, then learn which changes need a manual step, because Duende is registration only.
You connect Duende IdentityServer as an Authorization Server under Integrations → Authorization Servers. You enter your IdentityServer's authority, its Dynamic Client Registration endpoint, and the credentials of a client that may register clients. Apiable then registers a client for each subscription, with the plan's Active scopes.
Where do you connect Duende IdentityServer?
Go to Integrations → Authorization Servers, choose + Add AuthZ, select Duende on the Select Authorization Server type screen, then choose Connect Authorization Server.
- Open Integrations → Authorization Servers.
- Choose + Add AuthZ.
- On Select Authorization Server type, select Duende.
- Choose Connect Authorization Server. The connection form opens, titled Duende IdentityServer Configuration.
What does each Duende field mean?
The form has a name, a Server section and a Registration Credentials section. Fill in the required fields, then save.
| Field | Section | What to enter |
|---|---|---|
| Name | (top) | A label for this connection inside Apiable. Required, and unique across your Authorization Servers. |
| Authority URL | Server | Your IdentityServer's base address, for example https://ids.example.com. Required. Use https. |
| DCR Endpoint URL | Server | The Dynamic Client Registration endpoint. Required. Apiable fills it in as {authority}/connect/dcr. Override it only if yours differs. |
| Configuration Scope | Server | The scope Apiable requests to call the registration endpoint. Optional. Left blank, Apiable uses IdentityServer.Configuration. |
| Client ID | Registration Credentials | The client ID Apiable signs in with to register clients. Required. |
| Client Secret | Registration Credentials | The secret for that client. Required. |
What does the registration client need in IdentityServer?
It must be allowed the client credentials grant and the configuration scope. Apiable requests a token from {authority}/connect/token with that scope, then sends each registration to the DCR Endpoint URL with that token.
- Grant: client credentials.
- Allowed scope: the value of Configuration Scope, or
IdentityServer.Configurationif you left it blank. - Registration endpoint: your IdentityServer's Configuration API must accept registrations at the DCR Endpoint URL.
Apiable registers each subscription's client with the client credentials grant, Client Secret Basic authentication, and the plan's Active scopes. Define those scopes in IdentityServer before anyone subscribes. Apiable cannot create or read scopes on Duende.
How do you save and test the connection?
Click Save. The server's page opens and Apiable runs OIDC discovery in the background. Then click Test Connection to confirm IdentityServer is reachable. The status reads Connected, Error, or Not tested.
- Click Save. A new connection shows Save. When you edit a saved one, the button reads Save & Test Connection and runs a test after saving.
- The server's page opens. The results of OIDC discovery appear under Discovered Auth Methods. Discovery only accepts an
httpsAuthority URL. - Click Test Connection. Apiable reads
{authority}/.well-known/openid-configuration. - Read the status: Connected means IdentityServer responded. Error shows the start of the error message. Not tested means no test has run yet.
Connected means IdentityServer answered. It does not check the registration credentials or the configuration scope.
How do you confirm registration works?
On the saved connection, click Register Test Client. Apiable registers a client named test-client- followed by the connection's ID, and shows its Client ID and Client Secret once.
This confirms the token request, the configuration scope and the registration endpoint. Apiable cannot delete the test client, so remove it in IdentityServer when you are done.
Which changes need a manual step in IdentityServer?
Every change to a client after it is registered. Apiable records the change, but the client in IdentityServer stays as it was registered.
| What happens in Apiable | What reaches IdentityServer | What to do |
|---|---|---|
| A developer subscribes | A new client with the plan's Active scopes | Nothing. |
| You approve an Optional or Restricted request, or grant a scope from the subscription's Scopes tab | Nothing | Add the scope to the subscription's client in IdentityServer. The grant stays under Needs sync in the dashboard, and the consumer sees Syncing…. |
| You revoke a scope | Nothing | Remove the scope from the subscription's client in IdentityServer. |
| A subscription is cancelled | Nothing | Delete the subscription's clients in IdentityServer. |
| Credentials are regenerated | A new client with the plan's Active scopes | Delete the previous client in IdentityServer, and add back any scopes approved on top of the plan. |
Each client Apiable registers is named apiable:sub:{subscription ID}:plan:{plan ID}:env:{environment}, where the environment is production or sandbox. Use the name, or the Client ID shown on the subscription, to find the client in IdentityServer.
How do scopes and Sync work with Duende?
Apiable cannot read or write scopes on Duende. Define every scope your plans use in IdentityServer yourself, and keep the two lists in step.
- Sync with Auth Server on the Resource Groups page fails for Duende, in both directions.
- The plan's warning about scopes missing from the server does not appear, because Apiable cannot read IdentityServer's scopes.
- Export Scopes, on the Resource Groups page or a plan's Access Control tab, gives you the list to add by hand. See Resource groups and scopes.
Troubleshooting
Match the status or message to the fix.
| What you see | What to do |
|---|---|
| Status Not tested | No connection test has run yet. Open the server and click Test Connection. |
| Status Error with "Duende returned ..." | IdentityServer answered, but its discovery address returned an error status. Check the Authority URL. |
| Status Error with "Failed to reach Duende at ..." | Apiable could not reach IdentityServer. Check the Authority URL and that it is reachable from Apiable. |
| Discovery error "Issuer must be HTTPS (plain HTTP is only allowed for loopback issuers in local development)" | Change the Authority URL to its https address, save, then click Refresh under Discovered Auth Methods. |
| The Name field says "An authorization server named '{name}' already exists." | Each Authorization Server needs a unique name. Choose another name and save again. |
| Register Test Client returns an error | Check the Client ID and Client Secret, that the client may request the configuration scope, and the DCR Endpoint URL. |
| An approved scope stays under Needs sync, and the consumer sees Syncing… | Apiable cannot add scopes to a Duende client. Add the scope to the client in IdentityServer. Retry sync cannot complete it. |
| Sync with Auth Server fails | Apiable cannot read or write scopes on Duende. Export your scopes and define them in IdentityServer. |