This repository has been archived on 2023-08-20. You can view files and clone it, but cannot push or open issues or pull requests.
indieauth/docs/classes/Taproot-IndieAuth-Callback-AuthorizationFormInterface.html

352 lines
20 KiB
HTML
Raw Normal View History

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Documentation</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<base href="../">
<link rel="icon" href="images/favicon.ico"/>
<link rel="stylesheet" href="css/normalize.css">
<link rel="stylesheet" href="css/base.css">
<link href="https://fonts.googleapis.com/css2?family=Source+Sans+Pro:wght@400;600;700&display=swap" rel="stylesheet">
<link rel="stylesheet" href="css/template.css">
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.12.0/css/all.min.css" integrity="sha256-ybRkN9dBjhcS2qrW1z+hfCxq+1aBdwyQM5wlQoQVt/0=" crossorigin="anonymous" />
<script src="https://cdn.jsdelivr.net/npm/fuse.js@3.4.6"></script>
<script src="https://cdn.jsdelivr.net/npm/css-vars-ponyfill@2"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.12.0/js/all.min.js" integrity="sha256-0vuk8LXoyrmCjp1f0O300qo1M75ZQyhH9X3J6d+scmk=" crossorigin="anonymous"></script>
<script src="js/search.js"></script>
<script defer src="js/searchIndex.js"></script>
</head>
<body id="top">
<header class="phpdocumentor-header phpdocumentor-section">
<h1 class="phpdocumentor-title"><a href="" class="phpdocumentor-title__link">Documentation</a></h1>
<input class="phpdocumentor-header__menu-button" type="checkbox" id="menu-button" name="menu-button" />
<label class="phpdocumentor-header__menu-icon" for="menu-button">
<i class="fas fa-bars"></i>
</label>
<section data-search-form class="phpdocumentor-search">
<label>
<span class="visually-hidden">Search for</span>
<svg class="phpdocumentor-search__icon" width="21" height="20" viewBox="0 0 21 20" fill="none" xmlns="http://www.w3.org/2000/svg">
<circle cx="7.5" cy="7.5" r="6.5" stroke="currentColor" stroke-width="2"/>
<line x1="12.4892" y1="12.2727" x2="19.1559" y2="18.9393" stroke="currentColor" stroke-width="3"/>
</svg>
<input type="search" class="phpdocumentor-field phpdocumentor-search__field" placeholder="Loading .." disabled />
</label>
</section>
<nav class="phpdocumentor-topnav">
<ul class="phpdocumentor-topnav__menu">
</ul>
</nav>
</header>
<main class="phpdocumentor">
<div class="phpdocumentor-section">
<input class="phpdocumentor-sidebar__menu-button" type="checkbox" id="sidebar-button" name="sidebar-button" />
<label class="phpdocumentor-sidebar__menu-icon" for="sidebar-button">
Menu
</label>
<aside class="phpdocumentor-column -four phpdocumentor-sidebar">
<section class="phpdocumentor-sidebar__category">
<h2 class="phpdocumentor-sidebar__category-header">Namespaces</h2>
<h4 class="phpdocumentor-sidebar__root-namespace"><a href="namespaces/taproot.html"><abbr title="\Taproot">Taproot</abbr></a></h4>
<ul class="phpdocumentor-list">
<li><a href="namespaces/taproot-indieauth.html"><abbr title="\Taproot\IndieAuth">IndieAuth</abbr></a></li>
</ul>
</section>
<section class="phpdocumentor-sidebar__category">
<h2 class="phpdocumentor-sidebar__category-header">Reports</h2>
<h3 class="phpdocumentor-sidebar__root-package"><a href="reports/deprecated.html">Deprecated</a></h3>
<h3 class="phpdocumentor-sidebar__root-package"><a href="reports/errors.html">Errors</a></h3>
<h3 class="phpdocumentor-sidebar__root-package"><a href="reports/markers.html">Markers</a></h3>
</section>
<section class="phpdocumentor-sidebar__category">
<h2 class="phpdocumentor-sidebar__category-header">Indices</h2>
<h3 class="phpdocumentor-sidebar__root-package"><a href="indices/files.html">Files</a></h3>
</section>
</aside>
<div class="phpdocumentor-column -eight phpdocumentor-content">
<ul class="phpdocumentor-breadcrumbs">
<li class="phpdocumentor-breadcrumb"><a href="namespaces/taproot.html">Taproot</a></li>
<li class="phpdocumentor-breadcrumb"><a href="namespaces/taproot-indieauth.html">IndieAuth</a></li>
<li class="phpdocumentor-breadcrumb"><a href="namespaces/taproot-indieauth-callback.html">Callback</a></li>
</ul>
<article class="phpdocumentor-element -interface">
<h2 class="phpdocumentor-content__title">
AuthorizationFormInterface
</h2>
<aside class="phpdocumentor-element-found-in">
<abbr class="phpdocumentor-element-found-in__file" title="src/Callback/AuthorizationFormInterface.php"><a href="files/src-callback-authorizationforminterface.html"><abbr title="src/Callback/AuthorizationFormInterface.php">AuthorizationFormInterface.php</abbr></a></abbr>
:
<span class="phpdocumentor-element-found-in__line">11</span>
</aside>
<p class="phpdocumentor-summary">Authorization Form Interface</p>
<section class="phpdocumentor-description"></section>
<h3 id="toc">
Table of Contents
<a href="#toc" class="headerlink"><i class="fas fa-link"></i></a>
</h3>
<dl class="phpdocumentor-table-of-contents">
<dt class="phpdocumentor-table-of-contents__entry -method -public">
<a href="classes/Taproot-IndieAuth-Callback-AuthorizationFormInterface.html#method_showForm">showForm()</a>
<span>
&nbsp;: <abbr title="\Psr\Http\Message\ResponseInterface">ResponseInterface</abbr> </span>
</dt>
<dd>Show Form</dd>
<dt class="phpdocumentor-table-of-contents__entry -method -public">
<a href="classes/Taproot-IndieAuth-Callback-AuthorizationFormInterface.html#method_transformAuthorizationCode">transformAuthorizationCode()</a>
<span>
&nbsp;: array&lt;string|int, mixed&gt; </span>
</dt>
<dd>Transform Authorization Code</dd>
</dl>
<section class="phpdocumentor-methods">
<h3 class="phpdocumentor-elements__header" id="methods">
Methods
<a href="classes/Taproot-IndieAuth-Callback-AuthorizationFormInterface.html#methods" class="headerlink"><i class="fas fa-link"></i></a>
</h3>
<article
class="phpdocumentor-element
-method
-public
"
>
<h4 class="phpdocumentor-element__name" id="method_showForm">
showForm()
<a href="classes/Taproot-IndieAuth-Callback-AuthorizationFormInterface.html#method_showForm" class="headerlink"><i class="fas fa-link"></i></a>
</h4>
<aside class="phpdocumentor-element-found-in">
<abbr class="phpdocumentor-element-found-in__file" title="src/Callback/AuthorizationFormInterface.php"><a href="files/src-callback-authorizationforminterface.html"><abbr title="src/Callback/AuthorizationFormInterface.php">AuthorizationFormInterface.php</abbr></a></abbr>
:
<span class="phpdocumentor-element-found-in__line">55</span>
</aside>
<p class="phpdocumentor-summary">Show Form</p>
<code class="phpdocumentor-code phpdocumentor-signature ">
<span class="phpdocumentor-signature__visibility">public</span>
<span class="phpdocumentor-signature__name">showForm</span><span>(</span><span class="phpdocumentor-signature__argument"><span class="phpdocumentor-signature__argument__return-type"><abbr title="\Psr\Http\Message\ServerRequestInterface">ServerRequestInterface</abbr>&nbsp;</span><span class="phpdocumentor-signature__argument__name">$request</span></span><span class="phpdocumentor-signature__argument"><span>, </span><span class="phpdocumentor-signature__argument__return-type">array&lt;string|int, mixed&gt;&nbsp;</span><span class="phpdocumentor-signature__argument__name">$authenticationResult</span></span><span class="phpdocumentor-signature__argument"><span>, </span><span class="phpdocumentor-signature__argument__return-type">string&nbsp;</span><span class="phpdocumentor-signature__argument__name">$formAction</span></span><span class="phpdocumentor-signature__argument"><span>, </span><span class="phpdocumentor-signature__argument__return-type">array&lt;string|int, mixed&gt;|null&nbsp;</span><span class="phpdocumentor-signature__argument__name">$clientHApp</span></span><span>)</span><span> : </span><span class="phpdocumentor-signature__response_type"><abbr title="\Psr\Http\Message\ResponseInterface">ResponseInterface</abbr></span></code>
<section class="phpdocumentor-description"><p>This method is called once the IndieAuth Authorization Endpoint has confirmed that:</p>
<ul>
<li>The current user is authenticated</li>
<li>The client app (client_id) has been fetched and is valid</li>
<li>The client app redirect_uri is known to be valid</li>
</ul>
<p>It should build an authorization form which the currently logged-in user can use
to choose which scopes (if any) to grant the app.</p>
<p>Information specific to the IndieAuth authorization request can be found in
<code class="prettyprint">$request-&gt;getQueryParams()</code>. The parameters most likely to be of use to the authorization
form are:</p>
<ul>
<li>
<code class="prettyprint">scope</code>: a space-separated list of scopes which the client app is requesting. May be absent.</li>
<li>
<code class="prettyprint">client_id</code>: the URL of the client app. Should be shown to the user. This also makes a good “cancel” link.</li>
<li>
<code class="prettyprint">redirect_uri</code>: the URI which the user will be redirected to on successful authorization.</li>
</ul>
<p>The form MUST submit a POST request to <code class="prettyprint">$formAction</code>, with the <code class="prettyprint">taproot_indieauth_action</code>
parameter set to <code class="prettyprint">approve</code>.</p>
<p>The form MUST additionally include any CSRF tokens required to protect the submission.
Refer to whatever CSRF protection code youre using (e.g. <code class="prettyprint">\Taproot\IndieAuth\Middleware\DoubleSubmitCookieCsrfMiddleware</code>)
and make sure to include the required element. This will usually involve getting a
CSRF token with <code class="prettyprint">$request-&gt;getAttribute()</code> and including it in an <code class="prettyprint">&lt;input type=&quot;hidden&quot; …/&gt;</code>.</p>
<p>The form SHOULD offer the user the opportunity to choose which of the request scopes,
if any, they wish to grant. It should describe what effect each scope grants. If no scopes are
requested, tell the user that the app is only requesting authorization, not access to their data.</p>
<p>The form MAY offer the user UIs for additional token configuration, e.g. a custom token lifetime.
You may have to refer to the documentation for your instance of <code class="prettyprint">TokenStorageInterface</code> to ensure
that lifetime configuration works correctly. Any other additional data is not used by the IndieAuth
library, but, if stored on the access token, will be available to your app for use.</p>
</section>
<h5 class="phpdocumentor-argument-list__heading">Parameters</h5>
<dl class="phpdocumentor-argument-list">
<dt class="phpdocumentor-argument-list__entry">
<span class="phpdocumentor-signature__argument__name">$request</span>
: <span class="phpdocumentor-signature__argument__return-type"><abbr title="\Psr\Http\Message\ServerRequestInterface">ServerRequestInterface</abbr></span>
</dt>
<dd class="phpdocumentor-argument-list__definition">
<section class="phpdocumentor-description"><p>The current request.</p>
</section>
</dd>
<dt class="phpdocumentor-argument-list__entry">
<span class="phpdocumentor-signature__argument__name">$authenticationResult</span>
: <span class="phpdocumentor-signature__argument__return-type">array&lt;string|int, mixed&gt;</span>
</dt>
<dd class="phpdocumentor-argument-list__definition">
<section class="phpdocumentor-description"><p>The array returned from the Authentication Handler. Guaranteed to contain a 'me' key, may also contain additional keys e.g. 'profile'.</p>
</section>
</dd>
<dt class="phpdocumentor-argument-list__entry">
<span class="phpdocumentor-signature__argument__name">$formAction</span>
: <span class="phpdocumentor-signature__argument__return-type">string</span>
</dt>
<dd class="phpdocumentor-argument-list__definition">
<section class="phpdocumentor-description"><p>The URL which your form MUST submit to. Can also be used as the redirect URL for a logout process.</p>
</section>
</dd>
<dt class="phpdocumentor-argument-list__entry">
<span class="phpdocumentor-signature__argument__name">$clientHApp</span>
: <span class="phpdocumentor-signature__argument__return-type">array&lt;string|int, mixed&gt;|null</span>
</dt>
<dd class="phpdocumentor-argument-list__definition">
<section class="phpdocumentor-description"><p>If available, the microformats-2 structure representing the client app.</p>
</section>
</dd>
</dl>
<h5 class="phpdocumentor-return-value__heading">Return values</h5>
<span class="phpdocumentor-signature__response_type"><abbr title="\Psr\Http\Message\ResponseInterface">ResponseInterface</abbr></span>
&mdash;
<section class="phpdocumentor-description"><p>A response containing the authorization form.</p>
</section>
</article>
<article
class="phpdocumentor-element
-method
-public
"
>
<h4 class="phpdocumentor-element__name" id="method_transformAuthorizationCode">
transformAuthorizationCode()
<a href="classes/Taproot-IndieAuth-Callback-AuthorizationFormInterface.html#method_transformAuthorizationCode" class="headerlink"><i class="fas fa-link"></i></a>
</h4>
<aside class="phpdocumentor-element-found-in">
<abbr class="phpdocumentor-element-found-in__file" title="src/Callback/AuthorizationFormInterface.php"><a href="files/src-callback-authorizationforminterface.html"><abbr title="src/Callback/AuthorizationFormInterface.php">AuthorizationFormInterface.php</abbr></a></abbr>
:
<span class="phpdocumentor-element-found-in__line">90</span>
</aside>
<p class="phpdocumentor-summary">Transform Authorization Code</p>
<code class="phpdocumentor-code phpdocumentor-signature ">
<span class="phpdocumentor-signature__visibility">public</span>
<span class="phpdocumentor-signature__name">transformAuthorizationCode</span><span>(</span><span class="phpdocumentor-signature__argument"><span class="phpdocumentor-signature__argument__return-type"><abbr title="\Psr\Http\Message\ServerRequestInterface">ServerRequestInterface</abbr>&nbsp;</span><span class="phpdocumentor-signature__argument__name">$request</span></span><span class="phpdocumentor-signature__argument"><span>, </span><span class="phpdocumentor-signature__argument__return-type">array&lt;string|int, mixed&gt;&nbsp;</span><span class="phpdocumentor-signature__argument__name">$code</span></span><span>)</span><span> : </span><span class="phpdocumentor-signature__response_type">array&lt;string|int, mixed&gt;</span></code>
<section class="phpdocumentor-description"><p>This method is called on a successful authorization form submission. The <code class="prettyprint">$code</code> array
is a partially-constructed authorization code array, which is guaranteed to have the
following keys:</p>
<ul>
<li>
<code class="prettyprint">client_id</code>: the validated <code class="prettyprint">client_id</code> request parameter</li>
<li>
<code class="prettyprint">redirect_uri</code>: the validated <code class="prettyprint">redirect_uri</code> request parameter</li>
<li>
<code class="prettyprint">state</code>: the <code class="prettyprint">state</code> request parameter</li>
<li>
<code class="prettyprint">code_challenge</code>: the <code class="prettyprint">code_challenge</code> request parameter</li>
<li>
<code class="prettyprint">code_challenge_method</code>: the <code class="prettyprint">code_challenge_method</code> request parameter</li>
<li>
<code class="prettyprint">requested_scope</code>: the value of the <code class="prettyprint">scope</code> request parameter</li>
<li>
<code class="prettyprint">me</code>: the value of the <code class="prettyprint">me</code> key from the authentication result returned from the authentication request handler callback</li>
</ul>
<p>It may also have additional keys, which can come from the following locations:</p>
<ul>
<li>All keys from the the authentication request handler callback result which do not clash
with the keys listed above (with the exception of <code class="prettyprint">me</code>, which is always present). Usually
this is a <code class="prettyprint">profile</code> key, but you may choose to return additional data from the authentication
callback, which will be present in <code class="prettyprint">$data</code>.</li>
</ul>
<p>This method should add any additional data to the auth code, before it is persisted and
returned to the client app. Typically, this involves setting the <code class="prettyprint">scope</code> key to be a
valid space-separated scope string of any scopes granted by the user in the form.</p>
<p>If the form offers additional token configuration, this method should set any relevant
keys in <code class="prettyprint">$code</code> based on the form data in <code class="prettyprint">$request</code>.</p>
</section>
<h5 class="phpdocumentor-argument-list__heading">Parameters</h5>
<dl class="phpdocumentor-argument-list">
<dt class="phpdocumentor-argument-list__entry">
<span class="phpdocumentor-signature__argument__name">$request</span>
: <span class="phpdocumentor-signature__argument__return-type"><abbr title="\Psr\Http\Message\ServerRequestInterface">ServerRequestInterface</abbr></span>
</dt>
<dd class="phpdocumentor-argument-list__definition">
<section class="phpdocumentor-description"><p>The current request.</p>
</section>
</dd>
<dt class="phpdocumentor-argument-list__entry">
<span class="phpdocumentor-signature__argument__name">$code</span>
: <span class="phpdocumentor-signature__argument__return-type">array&lt;string|int, mixed&gt;</span>
</dt>
<dd class="phpdocumentor-argument-list__definition">
<section class="phpdocumentor-description"><p>The base authorization code data, to be added to.</p>
</section>
</dd>
</dl>
<h5 class="phpdocumentor-return-value__heading">Return values</h5>
<span class="phpdocumentor-signature__response_type">array&lt;string|int, mixed&gt;</span>
&mdash;
<section class="phpdocumentor-description"><p>The $code data after making any necessary changes.</p>
</section>
</article>
</section>
</article>
<section data-search-results class="phpdocumentor-search-results phpdocumentor-search-results--hidden">
<section class="phpdocumentor-search-results__dialog">
<header class="phpdocumentor-search-results__header">
<h2 class="phpdocumentor-search-results__title">Search results</h2>
<button class="phpdocumentor-search-results__close"><i class="fas fa-times"></i></button>
</header>
<section class="phpdocumentor-search-results__body">
<ul class="phpdocumentor-search-results__entries"></ul>
</section>
</section>
</section>
</div>
</div>
<a href="classes/Taproot-IndieAuth-Callback-AuthorizationFormInterface.html#top" class="phpdocumentor-back-to-top"><i class="fas fa-chevron-circle-up"></i></a>
</main>
<script>
cssVars({});
</script>
</body>
</html>