From 69e896a4a2e93758920c7e3c8a3faa6450be6647 Mon Sep 17 00:00:00 2001 From: Cullen Walsh Date: Sun, 19 Apr 2020 20:13:15 -0700 Subject: [PATCH] [KEYCLOAK-13841] Update typescript declarations for keycloak-nodejs-connect --- keycloak.d.ts | 109 ++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 102 insertions(+), 7 deletions(-) diff --git a/keycloak.d.ts b/keycloak.d.ts index 567d7a7f..bba37cdd 100644 --- a/keycloak.d.ts +++ b/keycloak.d.ts @@ -32,12 +32,35 @@ declare namespace KeycloakConnect { cookies?: boolean } - interface GrantProperties { - access_token?: string - refresh_token?: string - id_token?: string - expires_in?: string - token_type?: string + interface Claims { + // In the future it may make sense to populate this with some known claims + [key: string]: any + } + + interface EnforcerOptions { + response_mode?: 'permissions' | 'token' + resource_server_id?: string + claims?: Claims + } + + interface Permission { + id: string + scopes?: string[] + } + + interface AuthzRequest { + audience?: string + claim_token?: string + claim_token_format?: string + permissions: Permission[] + } + + interface AuthzRequestGrant extends AuthzRequest { + response_mode: undefined + } + + interface AuthzRequestOther extends AuthzRequest { + response_mode: 'decision' | 'permissions' } interface Token { @@ -47,6 +70,15 @@ declare namespace KeycloakConnect { hasRealmRole(roleName: string): boolean } + interface GrantProperties { + access_token?: Token + refresh_token?: Token + id_token?: Token + expires_in?: number + token_type?: string + __raw?: string + } + interface GrantManager { /** * Use the direct grant API to obtain a grant from Keycloak. @@ -280,7 +312,67 @@ declare namespace KeycloakConnect { * * @param {String} spec The protection spec (optional) */ - protect(spec: GaurdFn|string): express.RequestHandler + protect(spec?: GaurdFn|string): express.RequestHandler + + /** + * Enforce access based on the given permissions. This method operates in two modes, depending on the `response_mode` + * defined for this policy enforcer. + * + * If `response_mode` is set to `token`, permissions are obtained using an specific grant type. As a consequence, the + * token with the permissions granted by the server is updated and made available to the application via `request.kauth.grant.access_token`. + * Use this mode when your application is using sessions and you want to cache previous decisions from the server, as well automatically handle + * refresh tokens. This mode is especially useful for applications acting as client and resource server. + * + * If `response_mode` is set to `permissions`, the server only returns the list of granted permissions (no oauth2 response). + * Previous decisions are not cached and the policy enforcer will query the server every time to get a decision. + * This is the default `response_mode`. + * + * You can set `response_mode` as follows: + * + * keycloak.enforcer('item:read', {response_mode: 'token'}) + * + * In all cases, if the request is already populated with a valid access token (for instance, bearer tokens sent by clients to the application), + * the policy enforcer will first try to resolve permissions from the current token before querying the server. + * + * By default, the policy enforcer will use the `client_id` defined to the application (for instance, via `keycloak.json`) to + * reference a client in Keycloak that supports Keycloak Authorization Services. In this case, the client can not be public given + * that it is actually a resource server. + * + * If your application is acting as a client and resource server, you can use the following configuration to specify the client + * in Keycloak with the authorization settings: + * + * keycloak.enforcer('item:read', {resource_server_id: 'nodejs-apiserver'}) + * + * It is recommended to use separated clients in Keycloak to represent your frontend and backend. + * + * If the application you are protecting is enabled with Keycloak authorization services and you have defined client credentials + * in `keycloak.json`, you can push additional claims to the server and make them available to your policies in order to make decisions. + * For that, you can define a `claims` configuration option which expects a `function` that returns a JSON with the claims you want to push: + * + * app.get('/protected/resource', keycloak.enforcer(['resource:view', 'resource:write'], { + claims: function(request) { + return { + "http.uri": ["/protected/resource"], + "user.agent": // get user agent from request + } + } + }), function (req, res) { + // access granted + }); + * + * @param {String[]} expectedPermissions A single string representing a permission or an arrat of strings representing the permissions. For instance, 'item:read' or ['item:read', 'item:write']. + */ + enforcer(expectedPermissions: string|string[], options?: EnforcerOptions): express.RequestHandler + + /** + * Apply check SSO middleware to an application or specific URL. + * + * Check SSO will only authenticate the client if the user is already logged-in, + * if the user is not logged-in the browser will be redirected back + * to the originally-requested URL and remain unauthenticated. + * + */ + checkSso(): express.RequestHandler /** * Callback made upon successful authentication of a user. @@ -336,6 +428,9 @@ declare namespace KeycloakConnect { getGrantFromCode(code: string, req: express.Request, res: express.Response): Promise + checkPermissions(authz_req: AuthzRequestGrant, req: express.Request, cb?: (grant: Grant) => void): Promise + checkPermissions(authz_req: AuthzRequestOther, req: express.Request, cb?: (grant: Object) => void): Promise + loginUrl(uuid: string, redirectUrl: string): string logoutUrl(redirectUrl: string): string