telegram-crawler/data/web/blogfork.telegram.org/api/url-authorization.html

164 lines
11 KiB
HTML
Raw Normal View History

2022-05-14 00:37:40 +02:00
<!DOCTYPE html>
<html class="">
<head>
<meta charset="utf-8">
<title>Seamless Telegram Login</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta property="description" content="Handle Seamless Telegram Login URL authorization requests.">
<meta property="og:title" content="Seamless Telegram Login">
<meta property="og:image" content="faa06a44f2ab0cf059">
<meta property="og:description" content="Handle Seamless Telegram Login URL authorization requests.">
<link rel="icon" type="image/svg+xml" href="/img/website_icon.svg?4">
<link rel="apple-touch-icon" sizes="180x180" href="/img/apple-touch-icon.png">
<link rel="icon" type="image/png" sizes="32x32" href="/img/favicon-32x32.png">
<link rel="icon" type="image/png" sizes="16x16" href="/img/favicon-16x16.png">
<link rel="alternate icon" href="/img/favicon.ico" type="image/x-icon" />
<link href="/css/bootstrap.min.css?3" rel="stylesheet">
2024-08-02 02:44:36 +02:00
<link href="/css/telegram.css?240" rel="stylesheet" media="screen">
2022-05-14 00:37:40 +02:00
<style>
</style>
</head>
<body class="preload">
<div class="dev_page_wrap">
<div class="dev_page_head navbar navbar-static-top navbar-tg">
<div class="navbar-inner">
<div class="container clearfix">
<ul class="nav navbar-nav navbar-right hidden-xs"><li class="navbar-twitter"><a href="https://twitter.com/telegram" target="_blank" data-track="Follow/Twitter" onclick="trackDlClick(this, event)"><i class="icon icon-twitter"></i><span> Twitter</span></a></li></ul>
<ul class="nav navbar-nav">
<li><a href="//telegram.org/">Home</a></li>
<li class="hidden-xs"><a href="//telegram.org/faq">FAQ</a></li>
<li class="hidden-xs"><a href="//telegram.org/apps">Apps</a></li>
<li class="active"><a href="/api">API</a></li>
<li class=""><a href="/mtproto">Protocol</a></li>
<li class=""><a href="/schema">Schema</a></li>
</ul>
</div>
</div>
</div>
<div class="container clearfix">
<div class="dev_page">
<div id="dev_page_content_wrap" class=" ">
<div class="dev_page_bread_crumbs"><ul class="breadcrumb clearfix"><li><a href="/api" >API</a></li><i class="icon icon-breadcrumb-divider"></i><li><a href="/api/url-authorization" >Seamless Telegram Login</a></li></ul></div>
<h1 id="dev_page_title">Seamless Telegram Login</h1>
<div id="dev_page_content"><!-- scroll_nav -->
<p>Bots or Telegram websites may <a href="/bots/api#loginurl">ask users to login to a certain website via Telegram</a> when clicking on certain links or URL buttons in inline keyboards.</p>
<h3><a class="anchor" href="#bot-url-authorization" id="bot-url-authorization" name="bot-url-authorization"><i class="anchor-icon"></i></a>Bot URL authorization</h3>
<p>When the user clicks on <a href="/constructor/keyboardButtonUrlAuth">keyboardButtonUrlAuth</a>, <a href="/method/messages.requestUrlAuth">messages.requestUrlAuth</a> should be called, providing the <code>button_id</code> of the button and the ID and peer of the container message.
The returned <a href="/constructor/urlAuthResultRequest">urlAuthResultRequest</a> object will contain more details about the authorization request:</p>
<ul>
<li>The <code>domain</code> parameter will contain the domain name of the website on which the user will log in (example: <em>comments.app</em>).</li>
<li>The <code>bot</code> parameter will contain info about the bot which will be used for user authorization (example: <em>DiscussBot</em>).</li>
<li>The <code>request_write_access</code> will be set if the bot would like to send messages to the user.</li>
</ul>
<p>The info should be shown in a prompt:</p>
<div><div class="blog_image_wrap">
<a href="/file/811140015/1734/8VZFkwWXalM.97872/6127fa62d8a0bf2b3c" target="_blank"><img src="/file/811140909/1631/20k1Z53eiyY.23995/c541e89b74253623d9" title="TITLE" alt="TITLE" srcset="/file/811140015/1734/8VZFkwWXalM.97872/6127fa62d8a0bf2b3c , 2x"></a>
</div></div>
<p>If the user agrees to login to the URL, <a href="/method/messages.acceptUrlAuth">messages.acceptUrlAuth</a> should be called (eventually setting the <code>write_allowed</code> if the permission was requested and the user consented).
The result will be a <a href="/constructor/urlAuthResultAccepted">urlAuthResultAccepted</a> with the final URL to open, which will include a query string with the requested info and a hash that <a href="/widgets/login#receiving-authorization-data">must be verified upon receival by the service</a>.</p>
<p><a href="/constructor/urlAuthResultDefault">urlAuthResultDefault</a> could also be returned, instead, in which case the <code>url</code> of the <a href="/constructor/keyboardButtonUrlAuth">keyboardButtonUrlAuth</a> must be opened, instead.
The same must be done if the user opens the link while refusing the authorization request.</p>
<h3><a class="anchor" href="#link-url-authorization" id="link-url-authorization" name="link-url-authorization"><i class="anchor-icon"></i></a>Link URL authorization</h3>
<p>Telegram supports automatic authorization on certain websites upon opening an HTTP URL in-app, upon clicking a link in a message or clicking on a <a href="/constructor/keyboardButtonUrl">keyboardButtonUrl</a>.</p>
<h4><a class="anchor" href="#automatic-authorization" id="automatic-authorization" name="automatic-authorization"><i class="anchor-icon"></i></a>Automatic authorization</h4>
2022-11-15 00:55:37 +01:00
<p>Clients should automatically authenticate users when opening official Telegram websites, listed in the <a href="/api/config#autologin-domains"><code>autologin_domains</code> key</a> of the <a href="/api/config#client-configuration">client configuration object »</a>. </p>
2023-05-22 14:54:47 +02:00
<p>Upon clicking a link, the URL must be modified by appending the <a href="/constructor/config"><code>autologin_token</code> »</a> from the <a href="/api/config#mtproto-configuration">MTProto configuration object »</a> to the <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.4">query string</a>, like so: </p>
2022-05-14 00:37:40 +02:00
<p>Original URL: <code>https://somedomain.telegram.org/path?query=string#fragment=value</code><br>
Modified URL: <code>https://somedomain.telegram.org/path?query=string&amp;autologin_token=$autologin_token#fragment=value</code> </p>
2023-05-22 14:54:47 +02:00
<p>Make sure that the used <code>autologin_token</code> is no more than <code>10000</code> seconds old, if it is older it must be refetched before use with <a href="/method/help.getConfig">help.getConfig</a>. </p>
2022-05-14 00:37:40 +02:00
<h4><a class="anchor" href="#manual-authorization" id="manual-authorization" name="manual-authorization"><i class="anchor-icon"></i></a>Manual authorization</h4>
2022-11-15 00:55:37 +01:00
<p>Clients should show a confirmation prompt similar to the one used <a href="#bot-url-authorization">for bots</a>, to authenticate users when opening certain Telegram websites, listed in the <code>url_auth_domains</code> key of the <a href="/api/config#url-auth-domains">client configuration object »</a>. </p>
2022-05-14 00:37:40 +02:00
<p><a href="/method/messages.requestUrlAuth">messages.requestUrlAuth</a> should be called, providing only the original <code>url</code>.
The returned <a href="/constructor/urlAuthResultRequest">urlAuthResultRequest</a> object will contain more details about the authorization request:</p>
<ul>
<li>The <code>domain</code> parameter will contain the domain name of the website on which the user will log in (example: <em>comments.app</em>).</li>
<li>The <code>request_write_access</code> will be set if the website would like to send messages to the user.</li>
</ul>
<p>The info should be shown in a prompt. </p>
<p>If the user agrees to login to the URL, <a href="/method/messages.acceptUrlAuth">messages.acceptUrlAuth</a> should be called (eventually setting the <code>write_allowed</code> if the permission was requested and the user consented).
The result will be a <a href="/constructor/urlAuthResultAccepted">urlAuthResultAccepted</a> with the final URL to open. </p>
<p><a href="/constructor/urlAuthResultDefault">urlAuthResultDefault</a> could also be returned, instead, in which case the original URL must be opened, instead.
The same must be done if the user opens the link while refusing the authorization request.</p>
<h3><a class="anchor" href="#related-articles" id="related-articles" name="related-articles"><i class="anchor-icon"></i></a>Related articles</h3>
<h4><a class="anchor" href="#client-configuration" id="client-configuration" name="client-configuration"><i class="anchor-icon"></i></a><a href="/api/config">Client configuration</a></h4>
<p>The MTProto API has multiple configuration parameters that can be fetched with the appropriate methods.</p></div>
</div>
</div>
</div>
<div class="footer_wrap">
<div class="footer_columns_wrap footer_desktop">
<div class="footer_column footer_column_telegram">
<h5>Telegram</h5>
<div class="footer_telegram_description"></div>
Telegram is a cloud-based mobile and desktop messaging app with a focus on security and speed.
</div>
<div class="footer_column">
<h5><a href="//telegram.org/faq">About</a></h5>
<ul>
<li><a href="//telegram.org/faq">FAQ</a></li>
2022-09-09 12:10:24 +02:00
<li><a href="//telegram.org/privacy">Privacy</a></li>
2022-09-09 23:58:59 +02:00
<li><a href="//telegram.org/press">Press</a></li>
2022-05-14 00:37:40 +02:00
</ul>
</div>
<div class="footer_column">
<h5><a href="//telegram.org/apps#mobile-apps">Mobile Apps</a></h5>
<ul>
<li><a href="//telegram.org/dl/ios">iPhone/iPad</a></li>
2022-09-09 23:58:59 +02:00
<li><a href="//telegram.org/android">Android</a></li>
<li><a href="//telegram.org/dl/web">Mobile Web</a></li>
2022-05-14 00:37:40 +02:00
</ul>
</div>
<div class="footer_column">
<h5><a href="//telegram.org/apps#desktop-apps">Desktop Apps</a></h5>
<ul>
<li><a href="//desktop.telegram.org/">PC/Mac/Linux</a></li>
<li><a href="//macos.telegram.org/">macOS</a></li>
<li><a href="//telegram.org/dl/web">Web-browser</a></li>
</ul>
</div>
<div class="footer_column footer_column_platform">
<h5><a href="/">Platform</a></h5>
<ul>
<li><a href="/api">API</a></li>
<li><a href="//translations.telegram.org/">Translations</a></li>
<li><a href="//instantview.telegram.org/">Instant View</a></li>
</ul>
</div>
</div>
<div class="footer_columns_wrap footer_mobile">
<div class="footer_column">
<h5><a href="//telegram.org/faq">About</a></h5>
</div>
<div class="footer_column">
<h5><a href="//telegram.org/blog">Blog</a></h5>
</div>
<div class="footer_column">
<h5><a href="//telegram.org/apps">Apps</a></h5>
</div>
<div class="footer_column">
<h5><a href="/">Platform</a></h5>
</div>
<div class="footer_column">
2024-02-15 08:50:21 +01:00
<h5><a href="//telegram.org/press">Press</a></h5>
2022-05-14 00:37:40 +02:00
</div>
</div>
</div>
</div>
2022-12-10 23:50:15 +01:00
<script src="/js/main.js?47"></script>
2022-05-14 00:37:40 +02:00
<script src="/js/jquery.min.js?1"></script>
<script src="/js/bootstrap.min.js?1"></script>
<script>window.initDevPageNav&&initDevPageNav();
backToTopInit("Go up");
removePreloadInit();
</script>
</body>
</html>