<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<section id="publishing_authorization">
	<title>Tool publishing and authorization</title>
	<para>RCE components and integrated tools can be published to make them usable by other connected
		("remote") RCE instances. The publishing options for each component/tool can be defined in
		the "Component Publishing" view. In this view, each component can be assigned to one of
		three basic publication levels:<itemizedlist>
			<listitem>
				<para>Local (the default option): Components with the "local" setting can only be
					used on the local instance; they are not visible to other instances.</para>
			</listitem>
			<listitem>
				<para>Custom: This setting allows to make the component/tool available only to
					specific groups of users. To use this setting, one or more authorization groups
					have to be created first, which is explained in the next section. Each
					component/tool can then be assigned to one or multiple groups. Users on remote
					instances can see and use components if they are members of at least one of
					these groups.</para>
			</listitem>
			<listitem>
				<para>Public: Components with the "public" setting can be used by all connected RCE
					instances. This is equivalent to the tool and component publishing in earlier
					versions of RCE. Tools in the "public" group are also available over Uplink Connections
					and Remote Access connections.</para>
			</listitem>
		</itemizedlist><note>
			<para>If the "Component Publishing" view is not visible, you can open it from the
				"Window > Show View" menu. If it is not listed there, choose "Other" and select them
				from the "RCE" category.</para>
		</note></para>
	<section>
		<title>Managing authorization groups</title>
		<para>Authorization groups can be created and managed in the "Authorization Groups" dialog, which
			can be opened from the "Component Publishing" view. To create a new group, click the
			"Create Group"-button and enter a name for the group. To provide access to this group to
			other users, select the group in the list and click "Export Group Key". Copy the
			provided key from the dialog that appears, and pass it on to the users that you would
			like to invite to this group. <note>
				<para>IMPORTANT: This exported group key is similar to a password. When passing it
					to other users, make sure to use a communication medium that unauthorized users
					cannot easily intercept. For example, passing the key via an encrypted chat
					system provided by your employer, or a Team Site that is only accessible to
					project members, is usually secure enough. On the other hand, sharing it by
					email outside of your organization is usually unsafe, and we recommend using
					more secure alternatives.</para>
			</note></para>
		<para>When the other user receives this key, they can import it into their RCE instance by using
			the "Import Group Key" button in their "Authorization Groups" dialog. After importing a
			key on an RCE instance, all tools published for that group on connected RCE instances
			are visible and can be used like a "public" component. </para>
			<note><para>To provide access to tools over Uplink Connections, the tools either have to be 
			"public" or in an authorization group which name starts with "external_". Tools in other authorization
			groups are only accessible from the internal RCE network.</para></note>
	</section>
	<section>
		<title>Publishing tools on the command console</title>
		<para>Creating custom tool groups and publishing tools is also possible using the "auth" commands
			on the command line. A short reference:<itemizedlist>
				<listitem>
					<para><code>auth create &lt;name></code> - creates an authorization group</para>
				</listitem>
				<listitem>
					<para><code>auth list</code> - lists available access groups</para>
				</listitem>
				<listitem>
					<para><code>auth delete &lt;name/id></code> - deletes an authorization group; if
						the name is ambiguous (e.g. there are two groups named "groupName"), you
						need to add the randomly generated id behind it, separated with a colon
						(e.g. <code>groupName:2716ab2d25</code>)</para>
				</listitem>
				<listitem>
					<para><code>auth export &lt;name/id></code> - exports a group key in a form that can be
						imported by another instance via GUI or command line</para>
				</listitem>
				<listitem>
					<para><code>auth import &lt;exported key></code> - imports a group key exported via GUI (as
						described above) or via the <code>auth export</code> command. The group name
						is embedded in the exported key, and is set automatically.</para>
				</listitem>
				<listitem>
					<para><code>components set-auth &lt;component id> &lt;permissions></code> - sets the
						permissions for a component. Possible values for "permissions" are either
							"<code>local</code>", "<code>public</code>", or a comma-separated list
						of authorization groups/ids.</para>
				</listitem>
				<listitem>
					<para><code>components list-auth</code> - shows a list of all defined authorization settings.
						These settings are independent of whether a matching component exists, which
						means that settings are kept when a component is removed and later added
						again.</para>
				</listitem>
			</itemizedlist></para>
		<para>The component ids used in this commands can be derived as follows:<itemizedlist>
				<listitem>
					<para><code>rce/&lt;component name></code> for standard RCE components, e.g.
							"<code>rce/Parametric Study</code>"</para>
				</listitem>
				<listitem>
					<para><code>common/&lt;tool name></code> for integrated tools of type "common" e.g.
							"<code>common/ExampleTool</code>"</para>
				</listitem>
				<listitem>
					<para><code>cpacs/&lt;tool name></code> for integrated tools of type "CPACS" e.g.
							"<code>cpacs/CPACSExampleTool</code>"</para>
				</listitem>
			</itemizedlist></para>
	</section>
	
</section>
