Note: This project is deprecated and is no longer supported officially. Please see Multicloud apps with Istio documentation for more details. Adapter's docker image been removed from docker hub. If you want continue using you can clone the repository and maintain your own version of the image. The repository contains all the necessary scripts to make the migration easy. You can find the CD scripts in the bin directory. You will also have to point the helm chart to the new image repository.
By using the App Identity and Access adapter, you can centralize all of your identity management using any OIDC compliant identity provider. Because enterprises use clouds from multiple providers or a combination of on and off-premise solutions, heterogenous deployment models can help you to preserve existing infrastructure and avoid vendor lock-in. The adapter can be configured to work with any OIDC compliant identity provider, which enables it to control authentication and authorization policies in all environments including frontend and backend applications. And, it does it all without any change to your code or the need to redeploy your application.
A multicloud computing environment combines multiple cloud and/ or private computing environments into a single network architecture. By distributing workloads across multiple environments, you might find improved resiliency, flexibility, and greater cost-efficiency. To achieve the benefits, it's common to use a container-based applications with an orchestration layer, such as Kubernetes.
Figure. Multicloud deployment achieved with the App Identity and Access adapter.
Note: Due to an Istio limitation, the App Identity and Access adapter currently stores user session information internally and does not persist the information across replicas or over failover configurations. When using the adapter, limit your workloads to a single replica until the limitation is addressed.
Istio is an open source service mesh that layers transparently onto existing distributed applications that can integrate with Kubernetes. To reduce the complexity of deployments Istio provides behavioral insights and operational control over the service mesh as a whole. When App ID is combined with Istio, it becomes a scalable, integrated identity solution for multicloud architectures that does not require any custom application code changes. For more information, check out "What is Istio?".
Istio uses an Envoy proxy sidecar to mediate all inbound and outbound traffic for all services in the service mesh. By using the proxy, Istio extracts information about traffic, also known as telemetry, that is sent to the Istio component called Mixer to enforce policy decisions. The App Identity and Access adapter extends the Mixer functionality by analyzing the telemetry (attributes) against custom policies to control identity and access management into and across the service mesh. The access management policies are linked to particular Kubernetes services and can be finely tuned to specific service endpoints. For more information about policies and telemetry, see the Istio documentation.
If you're using a browser based application, you can use the Open ID Connect (OIDC) / OAuth 2.0 authorization_grant flow to authenticate your users. When an unauthenticated user is detected, they are automatically redirected to the authentication page. When the authentication completes, the browser is redirected to an implicit /oidc/callback endpoint where the adapter intercepts the request. At this point, the adapter obtains tokens from the identity provider and then redirects the user back to their originally requested URL.
To view the user session information including the session tokens, you can look in the Authorization header.
Authorization: Bearer <access_token> <id_token>
You can also logout authenticated users. When an authenticated user accesses any protected endpoint with oidc/logout appended as shown in the following example, they are logged out.
https://myhost/path/oidc/logout
If needed, a refresh token can be used to automatically acquire new access and identity tokens without your user's needing to re-authenticate. If the configured identity provider returns a refresh token, it is persisted in the session and used to retrieve new tokens when the identity token expires.
The adapter can be used in collaboration with the OAuth 2.0 JWT Bearer flow to protect service APIs by validating JWT Bearer tokens. The Bearer authorization flow expects a request to contain an Authorization header with a valid access token and an optional identity token. The expected header structure is Authorization=Bearer {access_token} [{id_token}]. Unauthenticated clients are returned an HTTP 401 response status with a list of the scopes that are needed to obtain authorization. If the tokens are invalid or expired, the API strategy returns an HTTP 401 response with an optional error component that says Www-Authenticate=Bearer scope="{scope}" error="{error}".
For more information about tokens and how they're used, see understanding tokens.
You can install the Adapter by using the accompanying Helm chart. You can configure the chart to match the needs of your project.
Before you get started, be sure you have the following prerequisites installed.
You can also use the IBM Cloud Kubernetes Service Managed Istio.
To install the chart, initialize Helm in your cluster, define the options that you want to use, and then run the install command.
-
If you're working with IBM Cloud Kubeneretes service, be sure to login and set the context for your cluster.
-
Enable Istio Policy Enforcement
-
Install Helm in your cluster.
helm init
You might want to configure Helm to use
--tlsmode. For help with enabling TLS, check out the Helm repository. If you enable TLS, be sure to append--tlsto every Helm command that you run. For more information about using Helm with IBM Cloud Kubernetes Service, see Adding services by using Helm Charts.
-
Install the chart.
$ helm repo add appidentityandaccessadapter https://raw.githubusercontent.com/ibm-cloud-security/app-identity-and-access-adapter/master/helm/appidentityandaccessadapter $ helm install --name appidentityandaccessadapter appidentityandaccessadapter/appidentityandaccessadapter
Helm lets you specify an image tag during installation with the set image.tag flag. For example,
helm install --name appidentityandaccessadapter appidentityandaccessadapter/appidentityandaccessadapter --set image.tag=0.5.0
The chart can also be installed locally. First clone this repo by
git clone [email protected]:ibm-cloud-security/app-identity-and-access-adapter.git, then install the charthelm install ./helm/appidentityandaccessadapter --name appidentityandaccessadapter.
An authentication or authorization policy is a set of conditions that must be met before a request can access a resource access. By defining an identity provider's service configuration and an access policy that outlines when a particular access control flow should be used, you can control access to any resource in your service mesh.
To see example CRD's, check out the samples directory.
Depending on whether you're protecting frontend or backend applications, create a policy configuration with one of the following options.
-
For frontend applications: Browser based applications that require user authentication can be configured to use the OIDC / OAuth 2.0 authentication flow. To define an
OidcConfigCRD containing the client used to facilitate the authentication flow with the Identity provider, use the following example as a guide.kind: OidcConfig metadata: name: oidc-provider-config namespace: sample-namespace spec: discoveryUrl: https://us-south.appid.cloud.ibm.com/oauth/v4/71b34890-a94f-4ef2-a4b6-ce094aa68092/oidc-discovery/.well-known clientId: 1234-abcd-efgh-4567 clientSecret: randomlyGeneratedClientSecret clientSecretRef: name: <name-of-my-kube-secret> key: <key-in-my-kube-secret>Field Type Required Description discoveryUrlstring yes A well-known endpoint that contains a JSON document of OIDC/OAuth 2.0 configuration information. clientIdstring yes An identifier for the client that is used for authentication. clientSecretstring *no A plain text secret that is used to authenticate the client. If not provided, a clientSecretRefmust exist.clientSecretRefobject no A reference secret that is used to authenticate the client. This can be used in place of the clientSecret.clientSecretRef.namestring yes The name of the Kubernetes Secret that contains the clientSecret.clientSecretRef.keystring yes The field within the Kubernetes Secret that contains the clientSecret.scopesarray[string] no The scopes to request ( openid profile emailby default). -
For backend applications: The OAuth 2.0 Bearer token spec defines a pattern for protecting APIs by using JSON Web Tokens (JWTs). Using the following configuration as an example, define a
JwtConfigCRD that contains the public key resource, which is used to validate token signatures.apiVersion: "security.cloud.ibm.com/v1" kind: JwtConfig metadata: name: samplejwtpolicy namespace: sample-app spec: jwksUrl: https://us-south.appid.cloud.ibm.com/oauth/v4/oauth/v4/71b34890-a94f-4ef2-a4b6-ce094aa68092/publickeys
Register application endpoints within a Policy CRD to validate incoming requests and enforce authentication rules. Each Policy applies exclusively to the Kubernetes namespace in which the object lives and can specify the services, paths, and methods that you want to protect.
apiVersion: "security.cloud.ibm.com/v1"
kind: Policy
metadata:
name: samplepolicy
namespace: sample-app
spec:
targets:
-
serviceName: <svc-sample-app>
paths:
- exact: /web/home
method: ALL
policies:
- policyType: oidc
config: <oidc-provider-config>
rules:
- claim: scope
match: ALL
source: access_token
values:
- appid_default
- openid
- claim: amr
match: ANY
source: id_token
values:
- cloud_directory
- google
- exact: /web/user
method: GET
policies:
- policyType: oidc
config: <oidc-provider-config>
redirectUri: https://github.com/ibm-cloud-security/app-identity-and-access-adapter
- prefix: /
method: ALL
policies:
-
policyType: jwt
config: <jwt-config>| Service Object | Type | Required | Description |
|---|---|---|---|
serviceName |
string | yes | The name of Kubernetes service in the Policy namespace that you want to protect. |
paths |
array[Path Object] | yes | A list of path objects that define the endpoints that you want to protect. If left empty, all paths are protected. |
| Path Object | Type | Required | Description |
|---|---|---|---|
exact or prefix |
string | yes | The path that you want to apply the policies on. Options include exact and prefix. exact matches the provides endpoints exactly with the last / trimmed. prefix matches the endpoints that begin with the route prefix that you provide. |
method |
enum | no | The HTTP method protected. Valid options ALL, GET, PUT, POST, DELETE, PATCH - Defaults to ALL: |
policies |
array[Policy] | no | The OIDC/JWT policies that you want to apply. |
| Policy Object | Type | Required | Description |
|---|---|---|---|
policyType |
enum | yes | The type of OIDC policy. Options include: jwt or oidc. |
config |
string | yes | The name of the provider config that you want to use. |
redirectUri |
string | no | The url you want the user to be redirected after successful authentication, default: the original request url. |
rules |
array[Rule] | no | The set of rules the you want to use for token validation. |
| Rule Object | Type | Required | Description |
|---|---|---|---|
claim |
string | yes | The claim that you want to validate. |
match |
enum | no | The criteria required for claim validation. Options include: ALL, ANY or NOT. The default is set to ALL. |
source |
enum | no | The token where you want to apply the rule. Options include: access_token or id_token. The default is set to access_token. |
values |
array[string] | yes | The required set of values for validation. |
To remove the adapter and all of the associated CRDs, you must delete the Helm chart and the associated signing and encryption keys.
helm delete --purge appidentityandaccessadapter
kubectl delete secret appidentityandaccessadapter-keys -n istio-systemIf you encounter an issue while working with the App Identity and Access adapter, consider the following FAQ's and troubleshooting techniques. For more help, You can ask questions through a forum or open a support ticket. When you are using the forums to ask a question, tag your question so that it is seen by the App ID development team.
- If you have technical questions about App ID, post your question on Stack Overflow and tag your question with "ibm-appid".
- For questions about the service and getting started instructions, use the dW Answers forum. Include the
appidtag.
For more information about getting support, see how do I get the support that I need.
By default, logs are styled as JSON and provided at an info visibility level to provide for ease of integration with external logging systems. To update the logging configuration, you can use the Helm chart. Supported logging levels include range -1 - 7 as shown in Zapcore. For more information about the levels, see the Zapcore documentation.
When you're manually viewing JSON logs, you might want to tail the logs and "pretty print" them by using jq.
Adapter
To see the adapter logs, you can use kubectl or access the pod from the appidentityandaccessadapter pod from the Kubernetes console.
$ alias adapter_logs="kubectl -n istio-system logs -f $(kubectl -n istio-system get pods -lapp=appidentityandaccessadapter -o jsonpath='{.items[0].metadata.name}')"
$ adapter_logs | jqMixer
If the adapter does not appear to receive requests, check the Mixer logs to ensure that it is successfully connected to the adapter.
$ alias mixer_logs="kubectl -n istio-system logs -f $(kubectl -n istio-system get pods -lapp=telemetry -o jsonpath='{.items[0].metadata.name}') -c mixer"
$ mixer_logs | jqThis package contains code licensed under the Apache License, Version 2.0 (the "License"). You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 and may also view the License in the LICENSE file within this package.