From f90bc835503f9377bfb84d8c35ca065b319ca79f Mon Sep 17 00:00:00 2001 From: nmoskaleva Date: Thu, 5 Feb 2026 15:13:39 +0100 Subject: [PATCH] Improve introductory sections --- src/pages/verify/getting-started/basics.mdx | 27 ++++++++++++-- .../verify/getting-started/oidc-intro.mdx | 32 ++++++++++++++++- src/pages/verify/getting-started/overview.mdx | 30 ++++++++++++++-- .../verify/guides/authorize-url-builder.mdx | 2 +- src/pages/verify/reference/glossary.mdx | 36 ++++++++++++++----- 5 files changed, 111 insertions(+), 16 deletions(-) diff --git a/src/pages/verify/getting-started/basics.mdx b/src/pages/verify/getting-started/basics.mdx index d606fae1..ca5ad11a 100644 --- a/src/pages/verify/getting-started/basics.mdx +++ b/src/pages/verify/getting-started/basics.mdx @@ -2,7 +2,7 @@ product: verify category: Getting Started sort: 1 -title: Learn the Basics +title: Basic Concepts subtitle: Learn the basics of Idura and familiarize yourself with the terminology. --- @@ -90,6 +90,27 @@ More detail on the formalities and process can be found in the section about [eI -## Where to go from here +## What's next? -This section introduced several core concepts of Idura. Next, we recommend learning [how Idura supports the OpenID Connect protocol](/verify/getting-started/oidc-intro/) and reviewing [best security practices for implementing OpenID Connect authentication](/verify/getting-started/best-security-practices/) in client applications. +Now that you understand the concepts, choose a path that suits you best: + +### Learn more + +Understand the protocol and how to implement it securely. + +- [Using OpenID Connect](/verify/getting-started/oidc-intro/): Learn how Idura supports the OpenID Connect protocol and how to add it to your app. +- [Security best practices](/verify/getting-started/best-security-practices/): Learn the essential security measures for client applications. + +### Experiment with tools + +Test authentication flows and configurations without writing code. + +- [OpenID Connect visualizer](/verify/guides/oidc-visualizer/): Run an interactive demo to see the authentication flow in action. +- [Authorize URL builder](/verify/guides/authorize-url-builder/): Construct and test authorize URLs,Explore various parameters and features available for each eID. + +### Start building + +Get this running in your application. + +- [Choose your integration](/verify/integrations/): Find the SDK that fits your tech stack. +- [Browse the guides](/verify/guides/): Need help with a specific feature? Check our detailed guides. diff --git a/src/pages/verify/getting-started/oidc-intro.mdx b/src/pages/verify/getting-started/oidc-intro.mdx index 1bc825d5..986feb4c 100644 --- a/src/pages/verify/getting-started/oidc-intro.mdx +++ b/src/pages/verify/getting-started/oidc-intro.mdx @@ -6,9 +6,14 @@ title: Using OpenID Connect subtitle: Learn how Idura supports the OpenID Connect protocol. --- +[OpenID Connect](https://docs.idura.app/verify/getting-started/oidc-intro/) is a widely adopted identity layer built on top of the [OAuth 2.0](https://docs.idura.app/verify/reference/glossary/#oauth-20) protocol. +It allows your application to verify the identity of an end-user based on the authentication performed by an Authorization Server (like Idura Verify), as well as to obtain basic profile information about that user. + +While OAuth 2.0 is about authorization (a user granting access to specific resources), OIDC is about authentication (proving who the user is). Idura Verify uses OIDC to provide a standardized, secure way to integrate various [eIDs](/verify/e-ids/) into your application without needing to build custom integrations for each one. + ## Using OpenID Connect to integrate with Idura Verify -Idura Verify is an OpenID Provider. It is integrated through the authentication API which follows the OpenID Connect and OAuth 2.0 specifications. +Idura Verify is an Authorization Server (OpenID Provider). It is integrated through the authentication API which follows the OpenID Connect and OAuth 2.0 specifications. ### Supported OpenID Connect Flows @@ -616,3 +621,28 @@ using System.Text; using System.Web.Security.AntiXss; "Basic " + Convert.ToBase64String(Encoding.ASCII.GetBytes(AntiXssEncoder.UrlEncode(IDURA_CLIENT_ID) + ":" + AntiXssEncoder.UrlEncode(IDURA_SECRET))) ``` + +## Where to go from here + +Choose your next steps: + +### Learn more + +Ensure your implementation is robust and understand the data you receive when users authenticate with an eID. + +- [Security best practices](/verify/getting-started/best-security-practices/): Learn how to secure your application. +- [JWT payloads](/verify/reference/token-contents/): See exactly what user data is returned by each eID. + +### Experiment with tools + +Test the flow and configurations without writing code. + +- [OpenID Connect visualizer](/verify/guides/oidc-visualizer/): Run an interactive demo to observe requests and responses exchanged as Authorization Code Flow unfolds. +- [Authorize URL builder](/verify/guides/authorize-url-builder/): Construct and test authorize URLs, and explore parameters available for each eID. + +### Start building + +Integrate eID authentication into your application. + +- [Choose your integration](/verify/integrations/): Find the SDK that fits your tech stack. +- [Browse the guides](/verify/guides/): Need help with a specific feature? Check our detailed guides. diff --git a/src/pages/verify/getting-started/overview.mdx b/src/pages/verify/getting-started/overview.mdx index 821fa791..741bcc3a 100644 --- a/src/pages/verify/getting-started/overview.mdx +++ b/src/pages/verify/getting-started/overview.mdx @@ -36,12 +36,38 @@ Technically, you can connect any application (written in any language or on any ## Which industry standards does Idura use? -At the core, being able to provide a service like Idura Verify is based on the premise of _federated authentication_, which means that you delegate the authentication and authorization process to a service outside of your own applications. +At its core, the ability to provide a service like Idura Verify is based on the premise of [federated authentication](/verify/reference/glossary/#federated-authentication). +This means delegating authentication and authorization process to a dedicated external service, rather than building it directly into your applications. Because federated authentication leverages one or more widely adopted industry standards, you are free to implement your applications without having to worry about how the actual identity services develop over time, or how they are secured. -The identity industry standards that we use here in Idura are: +The identity industry standards we use here at Idura are: - **Open Authorization (OAuth2)**: An authorization standard that allows a user to grant limited access to their resources on one site, to another site, without having to expose their credentials. - **OpenID Connect (OIDC)**: An identity layer that sits on top of OAuth2 and allows for easy verification of the user's identity, as well the ability to get basic profile information from the identity provider. - **JSON Web Tokens (JWT)**: An open standard that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. + +## What's next? + +You have the big picture. How would you like to proceed? + +### Understand the concepts + +New to federated authentication? + +- [Basic concepts in Idura Verify](/verify/getting-started/basics/): Understand the terminology used in this documentation. +- [Using OpenID Connect](/verify/getting-started/oidc-intro/): Learn how Idura Verify supports the protocol and how to add it to your app. + +### Explore eIDs + +See what identity providers are available and how to go live. + +- [Supported eIDs](/verify/e-ids/): Browse our catalog of electronic identities (Danish MitID, Norwegian BankID, etc.). +- [Get ready for production](/verify/guides/production/): See the checklist for going live. + +### Start building + +Already know your way around? Feel free to start building. + +- [Choose your integration](/verify/integrations/): Find the SDK that fits your tech stack. +- [Browse the guides](/verify/guides/): Need help with a specific feature? Check our detailed guides. diff --git a/src/pages/verify/guides/authorize-url-builder.mdx b/src/pages/verify/guides/authorize-url-builder.mdx index 400de15b..9cce5259 100644 --- a/src/pages/verify/guides/authorize-url-builder.mdx +++ b/src/pages/verify/guides/authorize-url-builder.mdx @@ -3,7 +3,7 @@ product: verify category: Guides & Tools sort: 0 title: Authorize URL builder -subtitle: Use our URL builder to explore the various features offers by Idura Verify and how to use them. +subtitle: Use our URL builder to explore the various features offered by Idura Verify and learn how to use them. --- import AuthorizeURLBuilder from '../../../components/AuthorizeURLBuilder'; diff --git a/src/pages/verify/reference/glossary.mdx b/src/pages/verify/reference/glossary.mdx index d9e33da0..c29f1d77 100644 --- a/src/pages/verify/reference/glossary.mdx +++ b/src/pages/verify/reference/glossary.mdx @@ -10,12 +10,18 @@ subtitle: A list of identity terms used in this documentation. ### ACR (Authentication Context Class Reference) -A specific value or set of values sent in an authorization request (as `acr_values`) to request a specific authentication method (e.g., a particular eID like Swedish BankID). Idura uses `acr_values` to determine which eID provider or authentication method should be invoked. +A specific value or set of values sent in an authorization request (as `acr_values`) to request a specific authentication method (e.g., a particular eID like Swedish BankID). +Idura uses `acr_values` to determine which eID provider or authentication method should be invoked. + +### Access Token + +A credential that represents authorization issued by the [Authorization Server](/verify/reference/glossary/#authorization-server) to the [Client Application](/verify/reference/glossary/#application-client-application) +to access resources on behalf of the end-user. An Access Token states what the bearer of the token is allowed to do, but not who the user is. [OAuth 2.0](/verify/reference/glossary/#oauth-20) uses Access Tokens. ### Application (Client Application) Your software (e.g., a web application, mobile application, or backend service) that integrates with Idura Verify to authenticate users. -We use the term "application" as defined by the client role in OAuth 2.0. +We use the term "application" as defined by the client role in The OAuth 2.0 Authorization Framework. Functionally, your software acts as the client in a client-server model, where Idura Verify serves as the Authentication Server. You create and configure an **Application** in your Idura Dashboard as a digital representation of your software. @@ -25,17 +31,21 @@ It also holds configurations for the specific eID providers your software will i ### Authorization Code Flow The most common OAuth 2.0 Authorization Grant type. The client application first receives a temporary authorization code via a browser redirect. -This code is then securely exchanged for tokens (ID Token, Access Token) at the Authorization Server's Token Endpoint over a secure "backchannel." The backchannel communication makes it suitable for confidential clients, while public clients must use the PKCE extension. +This code is then securely exchanged for tokens (ID Token, Access Token) at the Authorization Server's Token Endpoint over a secure "backchannel." +The backchannel communication makes it suitable for confidential clients, while public clients must use the PKCE extension. ### Authorization Flow (Authorization Grant) -In OAuth 2.0, an Authorization Flow describes a sequential workflow a client application follows to obtain an Authorization Grant (permission) from an Authorization Server (e.g., Idura Verify) to access protected resources on behalf of a user. -With Idura Verify, client applications can use Authorization Code Flow, PKCE, CIBA or Implicit Flow (for testing only). The choice of the flow depends on the application's requirements and characteristics, such as its ability to securely store a Client Secret or hold a private key (if using Private Key JWT for client authentication). +In OAuth 2.0, an Authorization Flow describes a sequential workflow a client application +follows to obtain an Authorization Grant (permission) from an Authorization Server (e.g., Idura Verify) to access protected resources on behalf of a user. +With Idura Verify, client applications can use Authorization Code Flow, PKCE, CIBA or Implicit Flow (for testing only). The choice of the flow depends on the application's requirements +and characteristics, such as its ability to securely store a Client Secret or hold a private key (if using Private Key JWT for client authentication). -### Authorization Request (Authorize URL) +### Authentication Request (Authorize URL) The initial request made by a client application to the Authorization Server's `/oauth2/authorize` endpoint to begin user authentication. -The Authorize URL contains several parameters (e.g., `scope`, `response_type`, `client_id`, `redirect_uri`, `acr_values` etc.) that inform the Authorization Server about the permissions requested and the specific authentication requirements. +The Authorize URL contains several parameters (e.g., `scope`, `response_type`, `client_id`, `redirect_uri`, `acr_values` etc.) that inform the Authorization Server +about the permissions requested and the specific authentication requirements. ### Authorization Server @@ -96,6 +106,12 @@ _Note: Starting at the end of 2025, all newly created domains will use the `idur A digital credential used to verify an individual's identity online. In simple terms, it's a digital equivalent of a physical ID (like a passport or driver's license), containing verified personal information about the holder. eIDs enable secure online authentication, transactions, and digital signing of documents. The Danish MitID, Swedish BankID, and German Personalausweis are examples of eIDs. +## F + +### Federated Authentication + +A model where a [Client Application](/verify/reference/glossary/#application-client-application) delegates the user authentication process to an external, trusted [Identity Provider](/verify/reference/glossary/#identity-provider-idp). + ## I ### ID Token @@ -145,11 +161,13 @@ Indicates the degree of confidence in the asserted identity of an end-user. eID ### OAuth 2.0 -An authorization standard that allows a user to grant limited access to their resources on one site to another site, without having to expose their credentials. OAuth 2.0 serves as the foundation for OpenID Connect (OIDC). +An authorization standard defined in [RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749), that allows a user to grant limited access to their resources on one site to another site, without having to expose their credentials. +OAuth 2.0 serves as the foundation for [OpenID Connect (OIDC)](/verify/reference/glossary/#openid-connect-oidc). ### OpenID Connect (OIDC) -An identity layer built on top of OAuth 2.0. It allows client applications to verify the identity of an end-user based on the authentication performed by an Authorization Server, as well as to obtain basic profile information about the end-user. Idura Verify's API is based on OIDC. +An identity layer built on top of [OAuth 2.0](/verify/reference/glossary/#oauth-20) and standardized in the [OIDC Core 1.0 specification](https://openid.net/specs/openid-connect-core-1_0.html). +It allows client applications to verify the identity of an end-user based on the authentication performed by an Authorization Server, as well as to obtain basic profile information about the end-user. Idura Verify's API is based on OIDC. ### OIDC Discovery Document (.well-known/openid-configuration)