Token Exchange - Authentication and Authorization Service

<!doctype html> <html lang="en" class="no-js"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width,initial-scale=1"> <link rel="icon" href="../../../assets/images/favicon.png"> <meta name="generator" content="mkdocs-1.3.1, mkdocs-material-8.5.3"> <title>Token Exchange - Authentication and Authorization Service</title> <link rel="stylesheet" href="../../../assets/stylesheets/main.7a952b86.min.css"> <link rel="stylesheet" href="../../../assets/stylesheets/palette.cbb835fc.min.css"> <link rel="stylesheet" href="../../../stylesheets/fonts.css"> <link rel="stylesheet" href="../../../stylesheets/kuri-kuri.css"> <script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce((e,_)=>(e<<5)-e+_.charCodeAt(0),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script> </head> <body dir="ltr" data-md-color-scheme="" data-md-color-primary="none" data-md-color-accent="none"> <input class="md-toggle" data-md-toggle="drawer" type="checkbox" id="__drawer" autocomplete="off"> <input class="md-toggle" data-md-toggle="search" type="checkbox" id="__search" autocomplete="off"> <label class="md-overlay" for="__drawer"></label> <div data-md-component="skip"> <a href="#token-exchange" class="md-skip"> Skip to content </a> </div> <div data-md-component="announce"> </div> <header class="md-header" data-md-component="header"> <nav class="md-header__inner md-grid" aria-label="Header"> <a href="../../.." title="Authentication and Authorization Service" class="md-header__button md-logo" aria-label="Authentication and Authorization Service" data-md-component="logo"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54Z"/></svg> </a> <label class="md-header__button md-icon" for="__drawer"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M3 6h18v2H3V6m0 5h18v2H3v-2m0 5h18v2H3v-2Z"/></svg> </label> <div class="md-header__title" data-md-component="header-title"> <div class="md-header__ellipsis"> <div class="md-header__topic"> <span class="md-ellipsis"> Authentication and Authorization Service </span> </div> <div class="md-header__topic" data-md-component="header-topic"> <span class="md-ellipsis"> Token Exchange </span> </div> </div> </div> <label class="md-header__button md-icon" for="__search"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.516 6.516 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5Z"/></svg> </label> <div class="md-search" data-md-component="search" role="dialog"> <label class="md-search__overlay" for="__search"></label> <div class="md-search__inner" role="search"> <form class="md-search__form" name="search"> <input type="text" class="md-search__input" name="query" aria-label="Search" placeholder="Search" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck="false" data-md-component="search-query" required> <label class="md-search__icon md-icon" for="__search"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.516 6.516 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5Z"/></svg> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11h12Z"/></svg> </label> <nav class="md-search__options" aria-label="Search"> <button type="reset" class="md-search__icon md-icon" title="Clear" aria-label="Clear" tabindex="-1"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M19 6.41 17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12 19 6.41Z"/></svg> </button> </nav> </form> <div class="md-search__output"> <div class="md-search__scrollwrap" data-md-scrollfix> <div class="md-search-result" data-md-component="search-result"> <div class="md-search-result__meta"> Initializing search </div> <ol class="md-search-result__list"></ol> </div> </div> </div> </div> </div> <div class="md-header__source"> <a href="https://gitlab.cern.ch/authzsvc/docs/authzsvc-docs" title="Go to repository" class="md-source" data-md-component="source"> <div class="md-source__icon md-icon"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><path d="M439.55 236.05 244 40.45a28.87 28.87 0 0 0-40.81 0l-40.66 40.63 51.52 51.52c27.06-9.14 52.68 16.77 43.39 43.68l49.66 49.66c34.23-11.8 61.18 31 35.47 56.69-26.49 26.49-70.21-2.87-56-37.34L240.22 199v121.85c25.3 12.54 22.26 41.85 9.08 55a34.34 34.34 0 0 1-48.55 0c-17.57-17.6-11.07-46.91 11.25-56v-123c-20.8-8.51-24.6-30.74-18.64-45L142.57 101 8.45 235.14a28.86 28.86 0 0 0 0 40.81l195.61 195.6a28.86 28.86 0 0 0 40.8 0l194.69-194.69a28.86 28.86 0 0 0 0-40.81z"/></svg> </div> <div class="md-source__repository"> authzsvc-docs </div> </a> </div> </nav> </header> <div class="md-container" data-md-component="container"> <main class="md-main" data-md-component="main"> <div class="md-main__inner md-grid"> <div class="md-sidebar md-sidebar--primary" data-md-component="sidebar" data-md-type="navigation" > <div class="md-sidebar__scrollwrap"> <div class="md-sidebar__inner"> <nav class="md-nav md-nav--primary" aria-label="Navigation" data-md-level="0"> <label class="md-nav__title" for="__drawer"> <a href="../../.." title="Authentication and Authorization Service" class="md-nav__button md-logo" aria-label="Authentication and Authorization Service" data-md-component="logo"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54Z"/></svg> </a> Authentication and Authorization Service </label> <div class="md-nav__source"> <a href="https://gitlab.cern.ch/authzsvc/docs/authzsvc-docs" title="Go to repository" class="md-source" data-md-component="source"> <div class="md-source__icon md-icon"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><path d="M439.55 236.05 244 40.45a28.87 28.87 0 0 0-40.81 0l-40.66 40.63 51.52 51.52c27.06-9.14 52.68 16.77 43.39 43.68l49.66 49.66c34.23-11.8 61.18 31 35.47 56.69-26.49 26.49-70.21-2.87-56-37.34L240.22 199v121.85c25.3 12.54 22.26 41.85 9.08 55a34.34 34.34 0 0 1-48.55 0c-17.57-17.6-11.07-46.91 11.25-56v-123c-20.8-8.51-24.6-30.74-18.64-45L142.57 101 8.45 235.14a28.86 28.86 0 0 0 0 40.81l195.61 195.6a28.86 28.86 0 0 0 40.8 0l194.69-194.69a28.86 28.86 0 0 0 0-40.81z"/></svg> </div> <div class="md-source__repository"> authzsvc-docs </div> </a> </div> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../.." class="md-nav__link"> CERN Authentication and Authorization Services </a> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_2" type="checkbox" id="__nav_2" > <label class="md-nav__link" for="__nav_2"> User authentication <span class="md-nav__icon md-icon"></span> </label> <nav class="md-nav" aria-label="User authentication" data-md-level="1"> <label class="md-nav__title" for="__nav_2"> <span class="md-nav__icon md-icon"></span> User authentication </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../authentication-options/" class="md-nav__link"> Authentication options </a> </li> <li class="md-nav__item"> <a href="../../two-factor-authentication/" class="md-nav__link"> Two factor authentication </a> </li> <li class="md-nav__item"> <a href="../../kerberos-authentication/" class="md-nav__link"> Kerberos </a> </li> <li class="md-nav__item"> <a href="../../time-limits/" class="md-nav__link"> Time limits </a> </li> <li class="md-nav__item"> <a href="../../autologon/" class="md-nav__link"> Autologon </a> </li> <li class="md-nav__item"> <a href="../../account-lifecycle/" class="md-nav__link"> Account Lifecycle </a> </li> <li class="md-nav__item"> <a href="../../unconfirmed-identities/" class="md-nav__link"> Unconfirmed identities </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--active md-nav__item--nested"> <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_3" type="checkbox" id="__nav_3" checked> <label class="md-nav__link" for="__nav_3"> Securing applications <span class="md-nav__icon md-icon"></span> </label> <nav class="md-nav" aria-label="Securing applications" data-md-level="1"> <label class="md-nav__title" for="__nav_3"> <span class="md-nav__icon md-icon"></span> Securing applications </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../../applications/application-configuration/" class="md-nav__link"> Configuring your application </a> </li> <li class="md-nav__item"> <a href="../../../applications/adding-application/" class="md-nav__link"> Adding your application to the service </a> </li> <li class="md-nav__item"> <a href="../../../applications/permission-scheme/" class="md-nav__link"> Defining the permissions scheme </a> </li> <li class="md-nav__item"> <a href="../../../applications/role-based-permissions/" class="md-nav__link"> Role based permissions (recommended) </a> </li> <li class="md-nav__item"> <a href="../../../applications/group-based-permissions/" class="md-nav__link"> Group based permissions </a> </li> <li class="md-nav__item"> <a href="../../../applications/sso-registration/" class="md-nav__link"> Registering your application to SSO </a> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_3_7" type="checkbox" id="__nav_3_7" > <label class="md-nav__link" for="__nav_3_7"> SAML <span class="md-nav__icon md-icon"></span> </label> <nav class="md-nav" aria-label="SAML" data-md-level="2"> <label class="md-nav__title" for="__nav_3_7"> <span class="md-nav__icon md-icon"></span> SAML </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../saml/saml/" class="md-nav__link"> About </a> </li> <li class="md-nav__item"> <a href="../../saml/config/" class="md-nav__link"> Configuration </a> </li> <li class="md-nav__item"> <a href="../../saml/shibboleth-integration/" class="md-nav__link"> Shibboleth integration </a> </li> <li class="md-nav__item"> <a href="../../saml/shibboleth-migration/" class="md-nav__link"> Shibboleth migration from the old SSO </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--active md-nav__item--nested"> <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_3_8" type="checkbox" id="__nav_3_8" checked> <label class="md-nav__link" for="__nav_3_8"> OIDC <span class="md-nav__icon md-icon"></span> </label> <nav class="md-nav" aria-label="OIDC" data-md-level="2"> <label class="md-nav__title" for="__nav_3_8"> <span class="md-nav__icon md-icon"></span> OIDC </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../oidc/" class="md-nav__link"> About </a> </li> <li class="md-nav__item"> <a href="../token-requests/" class="md-nav__link"> Token Requests </a> </li> <li class="md-nav__item"> <a href="../scopes/" class="md-nav__link"> Scopes </a> </li> <li class="md-nav__item"> <a href="../config/" class="md-nav__link"> OIDC configuration and usage </a> </li> <li class="md-nav__item"> <a href="../apache/" class="md-nav__link"> Apache configuration </a> </li> <li class="md-nav__item"> <a href="../securing-apis/" class="md-nav__link"> Securing APIs </a> </li> <li class="md-nav__item"> <a href="../api-access/" class="md-nav__link"> API Access </a> </li> <li class="md-nav__item md-nav__item--active"> <input class="md-nav__toggle md-toggle" data-md-toggle="toc" type="checkbox" id="__toc"> <label class="md-nav__link md-nav__link--active" for="__toc"> Token Exchange <span class="md-nav__icon md-icon"></span> </label> <a href="./" class="md-nav__link md-nav__link--active"> Token Exchange </a> <nav class="md-nav md-nav--secondary" aria-label="Table of contents"> <label class="md-nav__title" for="__toc"> <span class="md-nav__icon md-icon"></span> Table of contents </label> <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix> <li class="md-nav__item"> <a href="#request-token-exchange-permissions" class="md-nav__link"> Request token exchange permissions </a> </li> <li class="md-nav__item"> <a href="#make-the-token-exchange-request-to-cern-sso" class="md-nav__link"> Make the token exchange request to CERN SSO </a> </li> <li class="md-nav__item"> <a href="#use-the-exchanged-token" class="md-nav__link"> Use the exchanged token </a> </li> <li class="md-nav__item"> <a href="#token-exchange-and-roles" class="md-nav__link"> Token exchange and Roles </a> <nav class="md-nav" aria-label="Token exchange and Roles"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#step-1-the-user-logs-in-into-front-end-app-and-the-application-has-the-user-token" class="md-nav__link"> Step 1: The user logs in into front-end-app and the application has the user token. </a> </li> <li class="md-nav__item"> <a href="#step-2-front-end-app-exchanges-the-initial-token-with-the-target-audience-back-end-api" class="md-nav__link"> Step 2: front-end-app exchanges the initial token with the target audience back-end-api </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#limitation-chaining-public-clients" class="md-nav__link"> Limitation: Chaining public clients </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="../device-code/" class="md-nav__link"> Device Code </a> </li> <li class="md-nav__item"> <a href="../libraries/" class="md-nav__link"> Suggested libraries </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="../../../applications/examples/" class="md-nav__link"> Examples </a> </li> <li class="md-nav__item"> <a href="../../../applications/qa-environment/" class="md-nav__link"> QA Environment </a> </li> <li class="md-nav__item"> <a href="../../../applications/command-line-tools/" class="md-nav__link"> Command line tools </a> </li> <li class="md-nav__item"> <a href="../../faqs/" class="md-nav__link"> FAQs </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_4" type="checkbox" id="__nav_4" > <label class="md-nav__link" for="__nav_4"> Group Management System <span class="md-nav__icon md-icon"></span> </label> <nav class="md-nav" aria-label="Group Management System" data-md-level="1"> <label class="md-nav__title" for="__nav_4"> <span class="md-nav__icon md-icon"></span> Group Management System </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../../roadmap/group-missing-features/" class="md-nav__link"> Missing features </a> </li> <li class="md-nav__item"> <a href="../../../groups/special-groups/" class="md-nav__link"> Special groups </a> </li> <li class="md-nav__item"> <a href="../../../groups/dynamic-guidance/" class="md-nav__link"> Dynamic groups </a> </li> <li class="md-nav__item"> <a href="../../../groups/csv/" class="md-nav__link"> CSV </a> </li> <li class="md-nav__item"> <a href="../../../groups/e-groups-to-gms-sync-scenario/" class="md-nav__link"> E-Groups to GMS transition </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_5" type="checkbox" id="__nav_5" > <label class="md-nav__link" for="__nav_5"> Resources lifecycle and eligibility <span class="md-nav__icon md-icon"></span> </label> <nav class="md-nav" aria-label="Resources lifecycle and eligibility" data-md-level="1"> <label class="md-nav__title" for="__nav_5"> <span class="md-nav__icon md-icon"></span> Resources lifecycle and eligibility </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../../resources/resources/" class="md-nav__link"> Introduction </a> </li> <li class="md-nav__item"> <a href="../../../resources/resource-lifecycle-integration/" class="md-nav__link"> Integration </a> </li> <li class="md-nav__item"> <a href="../../../resources/resource-states/" class="md-nav__link"> Resource States </a> </li> <li class="md-nav__item"> <a href="../../../resources/push-rest-api/" class="md-nav__link"> Resources REST API (push) </a> </li> <li class="md-nav__item"> <a href="../../../resources/policies/" class="md-nav__link"> Custom Resource Policies </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_6" type="checkbox" id="__nav_6" > <label class="md-nav__link" for="__nav_6"> Documents <span class="md-nav__icon md-icon"></span> </label> <nav class="md-nav" aria-label="Documents" data-md-level="1"> <label class="md-nav__title" for="__nav_6"> <span class="md-nav__icon md-icon"></span> Documents </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../../documents/why-keycloak/" class="md-nav__link"> Why Keycloak </a> </li> <li class="md-nav__item"> <a href="../../../documents/presentations/" class="md-nav__link"> Presentations </a> </li> <li class="md-nav__item"> <a href="../../../documents/our-contributions/" class="md-nav__link"> Our contributions to Keycloak </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_7" type="checkbox" id="__nav_7" > <label class="md-nav__link" for="__nav_7"> Services <span class="md-nav__icon md-icon"></span> </label> <nav class="md-nav" aria-label="Services" data-md-level="1"> <label class="md-nav__title" for="__nav_7"> <span class="md-nav__icon md-icon"></span> Services </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../../services/" class="md-nav__link"> Overview </a> </li> <li class="md-nav__item"> <a href="../../../services/instances/" class="md-nav__link"> Links to instances </a> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_7_3" type="checkbox" id="__nav_7_3" > <label class="md-nav__link" for="__nav_7_3"> Authorization Service API <span class="md-nav__icon md-icon"></span> </label> <nav class="md-nav" aria-label="Authorization Service API" data-md-level="2"> <label class="md-nav__title" for="__nav_7_3"> <span class="md-nav__icon md-icon"></span> Authorization Service API </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../../authzsvc/overview/" class="md-nav__link"> Overview </a> </li> <li class="md-nav__item"> <a href="../../../authzsvc/managed-applications/" class="md-nav__link"> Managing applications for other users </a> </li> <li class="md-nav__item"> <a href="../../../authzsvc/roles/" class="md-nav__link"> Role definitions </a> </li> <li class="md-nav__item"> <a href="../../../authzsvc/model/" class="md-nav__link"> Model (attributes) </a> </li> <li class="md-nav__item"> <a href="../../../authzsvc/examples/" class="md-nav__link"> Examples </a> </li> </ul> </nav> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_8" type="checkbox" id="__nav_8" > <label class="md-nav__link" for="__nav_8"> Help <span class="md-nav__icon md-icon"></span> </label> <nav class="md-nav" aria-label="Help" data-md-level="1"> <label class="md-nav__title" for="__nav_8"> <span class="md-nav__icon md-icon"></span> Help </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../../trouble-shooting/edugain-authentication/" class="md-nav__link"> eduGAIN Authentication </a> </li> <li class="md-nav__item"> <a href="../../../trouble-shooting/2fa-tips/" class="md-nav__link"> 2FA Tips </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="../../../privacy-notice/" class="md-nav__link"> Privacy notice </a> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_10" type="checkbox" id="__nav_10" > <label class="md-nav__link" for="__nav_10"> Migration notes <span class="md-nav__icon md-icon"></span> </label> <nav class="md-nav" aria-label="Migration notes" data-md-level="1"> <label class="md-nav__title" for="__nav_10"> <span class="md-nav__icon md-icon"></span> Migration notes </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../../migrations/keycloak24/" class="md-nav__link"> Keycloak 24 </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="../../../contact/" class="md-nav__link"> Contact </a> </li> </ul> </nav> </div> </div> </div> <div class="md-sidebar md-sidebar--secondary" data-md-component="sidebar" data-md-type="toc" > <div class="md-sidebar__scrollwrap"> <div class="md-sidebar__inner"> <nav class="md-nav md-nav--secondary" aria-label="Table of contents"> <label class="md-nav__title" for="__toc"> <span class="md-nav__icon md-icon"></span> Table of contents </label> <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix> <li class="md-nav__item"> <a href="#request-token-exchange-permissions" class="md-nav__link"> Request token exchange permissions </a> </li> <li class="md-nav__item"> <a href="#make-the-token-exchange-request-to-cern-sso" class="md-nav__link"> Make the token exchange request to CERN SSO </a> </li> <li class="md-nav__item"> <a href="#use-the-exchanged-token" class="md-nav__link"> Use the exchanged token </a> </li> <li class="md-nav__item"> <a href="#token-exchange-and-roles" class="md-nav__link"> Token exchange and Roles </a> <nav class="md-nav" aria-label="Token exchange and Roles"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#step-1-the-user-logs-in-into-front-end-app-and-the-application-has-the-user-token" class="md-nav__link"> Step 1: The user logs in into front-end-app and the application has the user token. </a> </li> <li class="md-nav__item"> <a href="#step-2-front-end-app-exchanges-the-initial-token-with-the-target-audience-back-end-api" class="md-nav__link"> Step 2: front-end-app exchanges the initial token with the target audience back-end-api </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#limitation-chaining-public-clients" class="md-nav__link"> Limitation: Chaining public clients </a> </li> </ul> </nav> </div> </div> </div> <div class="md-content" data-md-component="content"> <article class="md-content__inner md-typeset"> <a href="https://gitlab.cern.ch/authzsvc/docs/authzsvc-docs/-/blob/master/docs/user-documentation/oidc/exchange-for-api.md" title="Edit this page" class="md-content__button md-icon"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20.71 7.04c.39-.39.39-1.04 0-1.41l-2.34-2.34c-.37-.39-1.02-.39-1.41 0l-1.84 1.83 3.75 3.75M3 17.25V21h3.75L17.81 9.93l-3.75-3.75L3 17.25Z"/></svg> </a> <h1 id="token-exchange">Token Exchange</h1> <div class="admonition warning"> <p class="admonition-title">Warning</p> <p>We only recommend using Token Exchange if you need to exchange tokens of logged in users from one application to another. If you just need to call a REST API using Client Credentials please go to <a href="../api-access/">API Access</a>.</p> </div> <p>Token exchange allows your OIDC application to exchange a token it receives during a user's login, for a token that is accepted by a different OIDC application.</p> <p>You may want to do this if, for example, you wish to call the <a href="https://authorization-service-api.web.cern.ch/swagger/index.html">Authorization Service</a> API or another downstream service.</p> <h2 id="request-token-exchange-permissions">Request token exchange permissions</h2> <p>From the <a href="https://application-portal.web.cern.ch">Application Portal</a>, select Token Exchange for your OIDC registration.</p> <p><img alt="select exchange" src="../../../images/select-exchange.png" /></p> <p>Now, select "Request token exchange permission" and search for the target application. For example, the Authorization Service API.</p> <p><img alt="choose target" src="../../../images/choose-target.png" /></p> <h2 id="make-the-token-exchange-request-to-cern-sso">Make the token exchange request to CERN SSO</h2> <p>Your application needs to make a second call to convert the original token into one that will be accepted by the target application.</p> <div class="highlight"><pre><span></span><code>curl -X POST \ -d "client_id=starting-client" \ -d "client_secret=SECRET" \ --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \ -d "subject_token=...." \ --data-urlencode "requested_token_type=urn:ietf:params:oauth:token-type:refresh_token" \ -d "audience=target-client" \ -d "scope=openid profile email" \ https://auth.cern.ch/auth/realms/cern/protocol/openid-connect/token </code></pre></div> <p>The following fields must be specified:</p> <table> <thead> <tr> <th>Field</th> <th>Value</th> </tr> </thead> <tbody> <tr> <td>client_id</td> <td>The clientId of <strong>your</strong> application</td> </tr> <tr> <td>client_secret (optional)</td> <td>The clientSecret of <strong>your</strong> application (not required for public clients)</td> </tr> <tr> <td>subject_token</td> <td>The access token that you received for <strong>your</strong> application</td> </tr> <tr> <td>audience</td> <td>The clientId of the target application</td> </tr> <tr> <td>scope (optional)</td> <td>The scope of the token</td> </tr> <tr> <td>grant_type</td> <td><code>urn:ietf:params:oauth:grant-type:token-exchange</code></td> </tr> <tr> <td>requested_token_type</td> <td><code>urn:ietf:params:oauth:token-type:refresh_token</code> (which returns both Refresh and Access tokens), <code>urn:ietf:params:oauth:token-type:access_token</code> or <code>urn:ietf:params:oauth:token-type:id_token</code></td> </tr> </tbody> </table> <p>More details can be found in the <a href="https://www.keycloak.org/docs/latest/securing_apps/#_token-exchange">Keycloak Documentation</a>.</p> <h2 id="use-the-exchanged-token">Use the exchanged token</h2> <p>CERN SSO will return a JSON response containing an access token minted for the target application, along with a refresh token. More details can be found in the <a href="https://www.keycloak.org/docs/latest/securing_apps/#making-the-request">Keycloak Documentation</a>.</p> <h2 id="token-exchange-and-roles">Token exchange and Roles</h2> <p>After exchanging a token, the new token will contain the roles of the logged in Identity for the target Application. This prevents the source Application from defining its own roles for the target Application. The result is not always so intuitive, so let's view it with an example:</p> <ul> <li>We have an application <em>front-end-app</em>, which is a single-page application that needs to call some other API with user tokens: <em>back-end-api</em>. In order to do this it uses token exchange.</li> <li>The owner of <em>front-end-app</em> defines the roles <code>frontend_user</code> and <code>administrator</code>, and links them to some user.</li> <li>The owner of <em>back-end-api</em> defines a role <code>backend_user</code>, and links it to the same user.</li> <li>The owner of <em>back-end-api</em> grants token exchange permissions to <em>front-end-app</em>.</li> </ul> <h3 id="step-1-the-user-logs-in-into-front-end-app-and-the-application-has-the-user-token">Step 1: The user logs in into <em>front-end-app</em> and the application has the user token.</h3> <p>Now the token will contain the roles <code>frontend_user</code> and <code>administrator</code>.</p> <h3 id="step-2-front-end-app-exchanges-the-initial-token-with-the-target-audience-back-end-api">Step 2: <em>front-end-app</em> exchanges the initial token with the target audience <em>back-end-api</em></h3> <p>Now the token will only contain the role <code>backend_user</code> (but not <code>frontend_user</code> or <code>administrator</code> as before). You can see here that the owner of <em>back-end-api</em> had full control over the roles assigned to this user, so the developer of <em>front-end-app</em> cannot assign roles like <code>administrator</code> to any regular user.</p> <h2 id="limitation-chaining-public-clients">Limitation: Chaining public clients</h2> <p>When a token is issued by Keycloak the <code>azp</code> (Authorized Party) is set to the client that initiated the flow. Public clients may only exchange tokens for which the <code>azp</code> is equal to their own <code>client_id</code>. For example:</p> <p><strong>Step 1:</strong> A user token is issued to public client_a. Resulting token:</p> <div class="highlight"><pre><span></span><code>{ "iss": "https://auth.cern.ch/auth/realms/cern", "aud": "client_a", "sub": "mcurie", "typ": "Bearer", "azp": "client_a", } </code></pre></div> <p><strong>Step 2:</strong> Public client_a exchanges the token for audience client_b. Resulting token:</p> <div class="highlight"><pre><span></span><code>{ "iss": "https://auth.cern.ch/auth/realms/cern", "aud": "client_b", "sub": "mcurie", "typ": "Bearer", "azp": "client_a", } </code></pre></div> <p><strong>Step 3:</strong> Public client_b exchanges the token for audience client_c. This step fails since the <code>azp</code> of the token presented is still equal to client_a. For it to work, client_b must provide a <code>client_secret</code> in its exchange request and therefore be a confidential rather than a public client. This would result in the following token:</p> <div class="highlight"><pre><span></span><code>{ "iss": "https://auth.cern.ch/auth/realms/cern", "aud": "client_c", "sub": "mcurie", "typ": "Bearer", "azp": "client_b", } </code></pre></div> </article> </div> </div> </main> <footer class="md-footer"> <nav class="md-footer__inner md-grid" aria-label="Footer" > <a href="../api-access/" class="md-footer__link md-footer__link--prev" aria-label="Previous: API Access" rel="prev"> <div class="md-footer__button md-icon"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11h12Z"/></svg> </div> <div class="md-footer__title"> <div class="md-ellipsis"> <span class="md-footer__direction"> Previous </span> API Access </div> </div> </a> <a href="../device-code/" class="md-footer__link md-footer__link--next" aria-label="Next: Device Code" rel="next"> <div class="md-footer__title"> <div class="md-ellipsis"> <span class="md-footer__direction"> Next </span> Device Code </div> </div> <div class="md-footer__button md-icon"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11H4Z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class="md-copyright"> Made with <a href="https://squidfunk.github.io/mkdocs-material/" target="_blank" rel="noopener"> Material for MkDocs </a> </div> </div> </div> </footer> </div> <div class="md-dialog" data-md-component="dialog"> <div class="md-dialog__inner md-typeset"></div> </div> <script id="__config" type="application/json">{"base": "../../..", "features": [], "search": "../../../assets/javascripts/workers/search.5bf1dace.min.js", "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.config.lang": "en", "search.config.pipeline": "trimmer, stopWordFilter", "search.config.separator": "[\\s\\-]+", "search.placeholder": "Search", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version.title": "Select version"}}</script> <script src="../../../assets/javascripts/bundle.37e9125f.min.js"></script> </body> </html>

CINXE.COM

Token Exchange - Authentication and Authorization Service