Skip to content

Commit 11d8a13

Browse files
darthmaimdarthmaim
committed
Describe application settings in docs
1 parent 16f181d commit 11d8a13

File tree

7 files changed

+145
-63
lines changed

7 files changed

+145
-63
lines changed

‎apps/web/app/dev/applications/[id]/page.tsx

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,7 @@ export default async function EditApplicationPage({ params }: EditApplicationPag
3737
return (
3838
<PageLayout>
3939
<Headline id="app">{application.name}</Headline>
40+
<p>Check the <a href="/dev/docs/manage-apps#settings">documentation</a> for more information on how to manage your application.</p>
4041

4142
<ApplicationForm application={application} applicationId={application.id} emails={emails} clients={application.clients}
4243
editApplicationAction={editApplication.bind(null, application.id)}

‎apps/web/app/dev/applications/create/page.tsx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ export default async function CreateApplicationPage() {
3131
<TextInput name="name"/>
3232
</Label>
3333

34-
<Label label={<>Type (See <Link href="/dev/docs/register-app#public-confidential">documentation</Link> for distinction)</>}>
34+
<Label label={<>Type (See <Link href="/dev/docs/manage-apps#public-confidential">documentation</Link> for distinction)</>}>
3535
<Select name="type" options={[{ value: '', label: '' }, ...ClientTypeOptions]}/>
3636
</Label>
3737

‎apps/web/app/dev/docs/manage-apps/page.tsx

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
import { PageLayout } from '@/components/Layout/PageLayout';
2+
import { PageTitle } from '@/components/Layout/PageTitle';
3+
import { Steps } from '@/components/Steps/Steps';
4+
import { Headline } from '@gw2treasures/ui/components/Headline/Headline';
5+
import { List } from '@gw2treasures/ui/components/Layout/List';
6+
import { ExternalLink } from '@gw2treasures/ui/components/Link/ExternalLink';
7+
import { Notice } from '@gw2treasures/ui/components/Notice/Notice';
8+
import Link from 'next/link';
9+
import styles from '../layout.module.css';
10+
import { Table } from '@gw2treasures/ui/components/Table/Table';
11+
import { Code } from '@/components/Layout/Code';
12+
13+
export default function DevDocsRegisterAppPage() {
14+
return (
15+
<PageLayout className={styles.layout}>
16+
<PageTitle>Manage Applications</PageTitle>
17+
18+
<Headline id="register">Register your Application</Headline>
19+
<p>The first step to getting an access token is to register your application.</p>
20+
21+
<Steps>
22+
<div>You need to <Link href="/login">Login</Link> to gw2.me.</div>
23+
<div>Go to the page to <Link href="/dev/applications/create">Create a new application</Link>.</div>
24+
<div>Enter the <b>name</b> of your application. The name must be unique and should tell the user what your application is about. The name is shown to the user when authorizing your Application and on their profile under <Link href="/applications">Authorized Applications</Link>.</div>
25+
<div>Select the type of your application. See <Link href="#public-confidential">Public vs. Confidential Applications</Link> for the differences. You cannot change this later.</div>
26+
<div>Select a verified email as contact email. This email will not be shown to users and is only used for important notifications about your application.</div>
27+
<div>Click <b>Create Application</b>.</div>
28+
<div>You will get redirected to the <b>Edit Application</b> page. You can also get there by locating your app on the <Link href="/dev/applications">Your Applications</Link> page and clicking <b>Manage</b>.</div>
29+
<div>Note your <b>Client ID</b>. Client IDs are considered public and can be embedded in a web page&apos;s source.</div>
30+
<div>
31+
<p>If you have created a <b>Confidential</b> application, you will also need a <b>Client Secret</b>. Click <b>Generate Client Secret</b>. You must copy the secret and store it somewhere safe.</p>
32+
<Notice type="warning">Treat client secrets as you would your password. You must keep it confidential and never expose it to users, even in an obscured form.</Notice>
33+
</div>
34+
</Steps>
35+
36+
<p>Your application is now created and you have everything necessary to <Link href="/dev/docs/access-tokens">get a token</Link>.</p>
37+
38+
39+
<Headline id="settings">Application settings</Headline>
40+
<p>These are the general settings of each application that can be edited after registering.</p>
41+
<Table>
42+
<thead>
43+
<tr>
44+
<Table.HeaderCell>Setting</Table.HeaderCell>
45+
<Table.HeaderCell>Description</Table.HeaderCell>
46+
</tr>
47+
</thead>
48+
<tbody>
49+
<tr>
50+
<td>Image</td>
51+
<td>A image to easily identify the application. The image will be resized to 128x128 pixels and svgs will be rasterized. The image will always be shown next to the application name.</td>
52+
</tr>
53+
<tr>
54+
<td>Name</td>
55+
<td>The unique name of the application. Users will see the name when authorizing applications and in their list of authorized applications.</td>
56+
</tr>
57+
<tr>
58+
<td>Description</td>
59+
<td>A short description of the application. Currently only shown on the <Link href="/discover">Discover</Link> page.</td>
60+
</tr>
61+
<tr>
62+
<td>Contact Email</td>
63+
<td>The contact email is used for important notifications about the application. This email is not shown to users.</td>
64+
</tr>
65+
<tr>
66+
<td>Public</td>
67+
<td>Public applications will be shown on the <Link href="/discover">Discover</Link> page.</td>
68+
</tr>
69+
<tr>
70+
<td>Public URL</td>
71+
<td>The URL of the application. This is required for public applications. The URL will be shown on the <Link href="/discover">Discover</Link> page.</td>
72+
</tr>
73+
<tr>
74+
<td>Privacy Policy URL</td>
75+
<td>Link to the privacy policy of the applications. This is shown to users when authorizing the application.</td>
76+
</tr>
77+
<tr>
78+
<td>Terms of Service URL</td>
79+
<td>Link to the terms of service of the applications. This is shown to users when authorizing the application.</td>
80+
</tr>
81+
</tbody>
82+
</Table>
83+
84+
<Headline id="client">OAuth2 Client Settings</Headline>
85+
<p>These settings can be used to configure the OAuth2 client.</p>
86+
87+
<Table>
88+
<thead>
89+
<tr>
90+
<Table.HeaderCell>Setting</Table.HeaderCell>
91+
<Table.HeaderCell>Description</Table.HeaderCell>
92+
</tr>
93+
</thead>
94+
<tbody>
95+
<tr>
96+
<td>Type</td>
97+
<td>The type of the OAuth2 client. This cannot be changed after creation. See <Link href="#public-confidential">Public vs. Confidential Applications</Link> for the differences.</td>
98+
</tr>
99+
<tr>
100+
<td>Client ID</td>
101+
<td>The public identifier of the OAuth2 client. This is used to identify the client to the authorization server.</td>
102+
</tr>
103+
<tr>
104+
<td>Client Secrets</td>
105+
<td>
106+
<p>The secrets used to authenticate the client to the authorization server. Only available for confidential clients. You can create multiple client secrets to allow for key rotation. Deleting a client secret instantly invalidates it.</p>
107+
<Notice type="warning">Treat client secrets as you would your password. You must keep it confidential and never expose it to users, even in an obscured form.</Notice>
108+
</td>
109+
</tr>
110+
<tr>
111+
<td>Redirect URIs</td>
112+
<td>List of allowed redirect URLs. Only https URLs are allowed. The URLs have to be exact matches, including the port and path. Localhost URLs can use http and don't need to specify a port.</td>
113+
</tr>
114+
</tbody>
115+
</Table>
116+
117+
<Headline id="public-confidential">Public vs. Confidential Applications</Headline>
118+
<p>The <ExternalLink href="https://tools.ietf.org/html/rfc6749#section-2.1">OAuth 2.0 specification</ExternalLink> classifies applications as either confidential or public clients. The main difference is whether your application is able to hold secrets securely. You will need to select the type of application when registering a new application.</p>
119+
120+
<p><b>Confidential applications</b> can hold credentials in a secure way without exposing them to unauthorized parties. They require a trusted backend server to store the secret(s).</p>
121+
<p>Confidential applications can use a Refresh Token to get a new access tokens after they expire.</p>
122+
123+
<p><b>Public applications</b> cannot hold secrets securely.</p>
124+
<p>Public applications will not be able to refresh expired access tokens. Instead they will have to get the user to reauthorize the application. They are also required to use PKCE during the authorization flow.</p>
125+
126+
<p>These are examples for public applications:</p>
127+
<List>
128+
<li>Native or mobile applications</li>
129+
<li>JavaScript-based client-side web application (such as a single-page app)</li>
130+
</List>
131+
</PageLayout>
132+
);
133+
}
134+
135+
export const metadata = {
136+
title: 'Register Application',
137+
};

‎apps/web/app/dev/docs/page.tsx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ export default function Docs() {
2626
<Headline id="use">Use gw2.me in your application</Headline>
2727

2828
<Steps>
29-
<div><Link href="/dev/docs/register-app">Register your application</Link>.</div>
29+
<div><Link href="/dev/docs/manage-apps#register">Register your application</Link>.</div>
3030
<div><Link href="/dev/docs/access-tokens">Get an access token</Link> by navigating the user to the authorization page.</div>
3131
<div>
3232
Access the Guild Wars 2 API by <Link href="/dev/docs/gw2-api">generating subtokens</Link> or

‎apps/web/app/dev/docs/register-app/page.tsx

Lines changed: 0 additions & 60 deletions
This file was deleted.

‎apps/web/app/dev/layout.tsx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ export default function DevLayout({ children }: LayoutProps) {
88
<NavLayout content={children}>
99
<Navigation prefix="/dev/" items={[
1010
{ segment: ['docs'], label: 'Documentation' },
11-
{ segment: ['docs', 'register-app'], label: 'Register your App' },
11+
{ segment: ['docs', 'manage-apps'], label: 'Manage Apps' },
1212
{ segment: ['docs', 'access-tokens'], label: 'Getting Access Tokens' },
1313
{ segment: ['docs', 'refresh-tokens'], label: 'Refreshing Tokens' },
1414
{ segment: ['docs', 'gw2-api'], label: 'Guild Wars 2 API' },

‎apps/web/next.config.ts

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,10 @@ const nextConfig: NextConfig = {
1414

1515
return config;
1616
},
17+
18+
redirects: async () => [
19+
{ source: '/dev/docs/register-app', destination: '/dev/docs/manage-apps', permanent: true },
20+
]
1721
};
1822

1923
export default nextConfig;

0 commit comments

Comments
 (0)